> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuro-tech.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Identity, authorization, and tokens

> Authorize IoT operations across network, conceptual, user, service, and device identities

Neuro IoT separates transport identity from the actor or asset represented by a request.

| Identity            | Purpose                                                               |
| ------------------- | --------------------------------------------------------------------- |
| Network identity    | XMPP bare JID (`account@domain`) controlled by a broker account.      |
| Network address     | Full JID (`account@domain/resource`) for one live connection.         |
| Conceptual identity | Manufacturer, model, serial number, and discovery/ownership metadata. |
| User identity       | Human actor originating an operation.                                 |
| Service identity    | Software service originating or delegating an operation.              |
| Device identity     | Machine or device originating an operation.                           |

XMPP authenticates connected entities with SASL. Presence subscriptions provide a first authorization boundary: an approved contact learns the full JID needed for direct `iq` request/response. This is useful but insufficient—every receiver must still authorize the stanza sender and requested operation.

## Distributed identity tokens

Provisioning tokens let a request carry user, service, or device identity across intermediaries.

| Item      | Value                                                        |
| --------- | ------------------------------------------------------------ |
| Namespace | `urn:nfi:iot:prov:t:1.0`                                     |
| Issuer    | Provisioning service component                               |
| Proof     | X.509 public certificate plus private-key challenge response |

Token issuance uses two exchanges:

1. The client sends `<getToken>` with the Base64 public certificate.
2. The issuer validates it and returns `<getTokenChallenge seqnr="…">` containing an OAEP-encrypted random challenge.
3. The client decrypts it with the private key and sends `<getTokenChallengeResponse>` with the same sequence number.
4. The issuer returns `<getTokenResponse token="issuer:random-value">`.

The private key never leaves the client.

## Validate a token

The first time a receiver sees a token from a sender:

1. Parse the provisioning-service address from the token.
2. Send `<getCertificate token="…">` to that service and obtain the public certificate.
3. Encrypt a fresh random value to the certificate and send `<tokenChallenge token="…">` to the request origin.
4. Intermediaries forward the challenge to the original actor.
5. Accept the identity only when `<tokenChallengeResponse>` decrypts to the original value.

Cache a successful binding only for a bounded period and invalidate it when the certificate, sender, token, or trust policy changes.

## Authorization order

1. Authenticate the XMPP connection and preserve the sender's full JID.
2. Validate any supplied identity tokens; absence is distinct from invalidity.
3. Resolve the owner/provisioning policy.
4. Authorize the operation, target node, fields/parameters, time range, and requested privileges.
5. Fail closed when policy or decision support is unavailable.

<Warning>A signed token proves control of key material and issuer recognition. It does not by itself grant permission to read a sensor or control an actuator.</Warning>