concepts
Intended Documentation
Authority Token Model
How Intended Authority Tokens are structured, cryptographically signed, verified, and managed through their lifecycle.
Authority Token Model#
An Authority Token is a cryptographically signed artifact that proves a specific action was verified against policy and authorized by the Intended runtime. This page covers the token's internal structure, how it is signed and verified, and how tokens behave through their lifecycle.
What an Authority Token Represents#
An Authority Token is not an identity credential and not an access token in the OAuth sense. It is an authorization proof — a signed record that a particular intent was submitted to the authority runtime, evaluated against the tenant's policy set, and resulted in an explicit allow decision.
The token encodes everything needed to independently verify that proof:
- The action and resource that were authorized
- The identity that requested authorization
- The tenant context
- The policies that were evaluated
- When the authorization was granted and when it expires
- A cryptographic signature that binds all of the above together
Token Structure#
Authority Tokens use a compact, signed format with three sections: header, payload, and signature.
Header#
The header identifies the signing algorithm and key:
| Field | Description |
|---|---|
alg | The signing algorithm. Intended uses RS256 for Authority Tokens. |
typ | The token type. Always authority+jwt to distinguish Authority Tokens from other JWT-format tokens. |
kid | The key identifier, scoped to the tenant. Used by verifiers to select the correct public key. |
Payload#
The payload contains the authorization claims:
| Claim | Description |
|---|---|
iss | Issuer. Always intended:runtime, confirming the token was issued by the Intended runtime. |
sub | Subject. The identity that requested authorization. |
aud | Audience. The downstream service expected to consume this token. |
iat | Issued-at timestamp (Unix seconds). |
exp | Expiration timestamp (Unix seconds). The token is invalid after this time. |
tid | Tenant identifier. Scopes the token to a specific tenant's trust boundary. |
act | The authorized action. |
res | The authorized resource. |
pol | The policies evaluated, including their version numbers. |
ctx | Context metadata from the original intent, preserved for audit correlation. |
jti | Token identifier. A unique ID for this specific token, used for revocation and audit lookup. |
Signature#
The signature is produced by signing the encoded header and payload with the tenant's private signing key:
The final token is the three sections concatenated with dots:
Cryptographic Signing#
Key Management#
Each tenant has a dedicated signing key pair. The private key is used by the Intended runtime to sign tokens; the public key is distributed to downstream services for verification.
Info
Tenant signing keys are isolated — the runtime uses separate key material for each tenant. A compromise of one tenant's key does not affect any other tenant. See Tenant Trust Boundary for the full isolation model.
Key properties:
- Algorithm: RSA with SHA-256 (RS256)
- Key storage: Private keys are stored in the runtime's secure key store and are not exportable
- Key rotation: Keys can be rotated without invalidating in-flight tokens. The
kidfield in the token header allows verifiers to select the correct key during a rotation window - Key distribution: Public keys are available via a JWKS endpoint scoped to each tenant
Signing Process#
Assemble the claims
The runtime constructs the payload from the evaluation result — the authorized action, resource, subject, tenant, and policy references.
Set temporal bounds
The runtime sets iat to the current time and exp based on the token TTL configured for the tenant. The default TTL is 5 minutes. Shorter TTLs reduce the window during which a compromised token could be misused.
Assign a token ID
The runtime generates a unique jti for the token. This ID is recorded in the audit log and can be used to look up or revoke the specific token.
Sign the token
The runtime signs the assembled header and payload using the tenant's current private key. The kid in the header references this key.
Return the token
The signed token is returned to the caller as part of the evaluation response.
Verification#
Verification is the process by which a downstream service confirms that a decision token is authentic, unexpired, and applicable to the request being made.
Verification Steps#
Parse the token
Split the token into its three sections (header, payload, signature) and base64url-decode each.
Retrieve the public key
Using the kid from the header, retrieve the corresponding public key from the tenant's JWKS endpoint. Public keys should be cached locally with a refresh interval (the Intended SDK handles this automatically).
Verify the signature
Verify the ECDSA signature against the encoded header and payload using the public key. If the signature does not match, reject the token immediately.
Check temporal validity
Confirm that the current time is after iat and before exp. Apply a small clock skew tolerance (the SDK defaults to 30 seconds) to account for clock differences between services.
Validate the audience
Confirm that the aud claim matches the identity of the service performing the verification. A token intended for service:customer-api should be rejected by service:billing-api.
Match the request
Confirm that the act and res claims match the action and resource of the request being made. A token authorizing read on customer:record:12345 does not authorize write on that same record, nor read on a different record.
Check tenant scope
Confirm that the tid claim matches the tenant context of the verifying service. Tokens from one tenant cannot be used in another tenant's context.
Warning
Every step in the verification sequence is required. Skipping the audience or resource check weakens the security model and can allow token misuse. The Intended verification SDKs enforce all steps by default.
Offline Verification#
Token verification does not require a call back to the Intended runtime. The verifying service only needs the tenant's public key, which it obtains from the JWKS endpoint and caches locally. This design means:
- Verification latency is sub-millisecond (a local cryptographic operation)
- The Intended runtime is not a single point of failure in the enforcement path
- Services can verify tokens even during a temporary runtime outage, as long as they have cached keys
Token Lifecycle#
Issuance#
Tokens are issued only by the Intended runtime, only after a successful policy evaluation, and only within the evaluated tenant's context.
Validity Window#
Every token has a finite validity window defined by iat and exp. The default TTL is 5 minutes, configurable per tenant. Shorter windows are recommended for sensitive operations.
Single Use vs. Reuse#
Decision tokens are not explicitly single-use by default. A token remains valid until it expires. However, because tokens are bound to a specific action and resource, the practical scope for reuse is narrow — the same caller would need to perform the exact same operation on the exact same resource within the token's TTL.
For operations where strict single-use is required, the downstream service can record the jti and reject any token it has seen before.
Revocation#
In cases where a token must be invalidated before its natural expiry — for example, if the policy that authorized it is rolled back — the runtime supports explicit revocation:
- The operator or API client calls the revocation endpoint with the token's
jti - The runtime publishes the revocation to a revocation list
- Verifying services that check the revocation list will reject the token
Info
Revocation checking is optional and introduces a dependency on the revocation list service. For most use cases, short token TTLs provide sufficient protection without the complexity of revocation infrastructure.
Expiry#
Once a token's exp time passes, it is no longer valid. No explicit cleanup is needed — expired tokens are simply rejected on verification. The audit log retains the record of the token's issuance and any verification events.
Token vs. Identity Credentials#
It is important to distinguish decision tokens from identity credentials (e.g., OAuth access tokens, API keys):
| Property | Identity Credential | Decision Token |
|---|---|---|
| Purpose | Proves who the caller is | Proves what was authorized |
| Issuer | Identity provider | Intended runtime |
| Scope | Broad (multiple actions) | Narrow (single action + resource) |
| Lifetime | Minutes to hours | Seconds to minutes |
| Verification | Against identity provider | Against tenant public key |
| Binding | Bound to an identity | Bound to an intent |
A single request may carry both an identity credential (to authenticate the caller) and a decision token (to prove authorization). These are complementary, not redundant.
Related Resources#
- What Is Intended — platform overview
- Authority Runtime Pipeline — how tokens are issued within the pipeline
- Tenant Trust Boundary — how tenant key isolation works
- Verify a Token — practical guide to token verification using the API and CLI