concepts

Intended Documentation

Authority Token Model

The Authority Token's real structure, Ed25519 signing, per-tenant keys, single-use nonce, 300-second lifetime, and the exact local verification steps and failure reasons.

6 min read

Authority Token Model#

An Authority Token is the cryptographic proof that a specific action was verified against policy and approved. It is not an identity credential and not an OAuth access token — it is a single-use authorization proof, bound to one intent. Intended decides and signs; your agent acts, carrying the token, and the service it calls verifies the token locally before acting. An Authority Token is minted only on an APPROVED decision; DENIED and ESCALATED produce none.

A token is minted on APPROVED as an Ed25519 JWT, carried by the customer's agent, verified locally by the service it calls, then its nonce is consumed for single use. Replay, expiry, kid mismatch, and revocation are rejection states. — Authority Token lifecycle

Structure#

The Authority Token is an Ed25519 JWT — three base64url sections (header, claims, signature) joined by dots.

json

{ "alg": "EdDSA", "typ": "JWT", "kid": "tenant_acme_prod-1749200000000-9f3a1c2b" }

Field	Value
`alg`	`EdDSA` — Ed25519 (Edwards-curve) signature.
`typ`	`JWT`.
`kid`	The tenant's signing-key id. Verifiers use it to select the correct public key; pinning it is mandatory.

Claims#

The claims bind the token to exactly one intent, tenant, and target:

Claim	Meaning
`intentId`	The intent this token authorizes (UUID).
`tenantId`	Tenant scope.
`adapterId`	The consumer the token is bound to (`decision-only` for decisions from `/v1/agent-intent`).
`adapterTarget`	The specific target the action is bound to.
`targetSystem`	The system the action targets.
`proposedAction`	The action that was approved.
`decision`	Always `APPROVED` — only approvals mint tokens.
`issuedAt` / `expiresAt`	Validity window (see lifetime below).
`nonce`	A ≥32-character random value enforcing single use.

At signing time the runtime also sets the standard JWT registered claims iss: "intended-authority", aud: <adapterId>, and integer iat / exp.

json

{
  "intentId": "8aa3f5f6-b1a9-4c5b-a29f-b489f7d0be58",
  "tenantId": "tenant_acme_prod",
  "adapterId": "decision-only",
  "adapterTarget": "acme/platform-api",
  "targetSystem": "acme/platform-api",
  "proposedAction": "Deploy platform-api to staging",
  "decision": "APPROVED",
  "issuedAt": "2026-06-06T14:30:00.000Z",
  "expiresAt": "2026-06-06T14:35:00.000Z",
  "nonce": "9f3a1c2b7e4d8a60f1b2c3d4e5f60718",
  "iss": "intended-authority",
  "aud": "decision-only"
}

Lifetime#

Authority Tokens are short-lived by design: the default and the hard maximum lifetime are both 300 seconds (5 minutes). A token cannot be issued with a longer TTL — the signer rejects it. Combined with single-use semantics, this keeps the window in which a leaked token could be misused minimal.

Signing keys#

Each tenant has its own signing key pair; one tenant's key never signs another tenant's tokens.

Algorithm — algorithm-agnostic, Ed25519 by default (RSA‑4096 / ES256 selectable).
At rest — private keys are encrypted (AES‑256‑GCM) in the key store and are not exportable.
Lifecycle — keys are ACTIVE, PREVIOUS, or RETIRED. Verification accepts ACTIVE and PREVIOUS; RETIRED keys are excluded.
Rotation — rotating a key issues new tokens under a new kid while in-flight tokens signed by the now-PREVIOUS key still verify, so rotation causes no downtime.

Verification#

Verification is local: the consumer needs only the tenant's public key for the token's kid, which it can cache and refresh on a schedule. It never calls back to the Intended runtime. Run these checks in the service your agent calls (or the gateway you run in front of it) before the action takes effect; @intended/verify implements the signature and claim checks.

Select the key by kid

Decode the header, read kid, and load the tenant's public key for it. An unknown or unpinned kid is rejected (TOKEN_KID_MISMATCH).

Verify the Ed25519 signature

A failed signature check is rejected (TOKEN_SIGNATURE_INVALID).

Validate the claims

Assert tenantId, adapterId, and adapterTarget match this action, decision === "APPROVED", iss/aud match, and the token is unexpired and within the 300s max TTL.

Consume the nonce

Your service records the nonce atomically (unique per tenant) and rejects a replay whose nonce is already consumed. This is what makes the token single-use.

Verifying in code#

import { verifyToken } from "@intended/verify";

const result = await verifyToken({
  token,                         // the authorityDecisionToken from POST /intent
  publicKeyPem,                  // tenant public key for the token's kid
  expectedKid: kid,              // pin the key id (required)
  expectedTenantId: "tenant_acme_prod",
  expectedAdapterId: "decision-only",
  maxTokenTtlSeconds: 300,
  clockSkewSeconds: 60,
});

if (!result.valid) throw new Error(result.reason); // e.g. TOKEN_EXPIRED
// result.claims is the validated claim set

Failure reasons#

Verification is fail-closed: any failure rejects the action. Common reasons:

Reason	Cause
`TOKEN_SIGNATURE_INVALID`	Signature does not verify against the key
`TOKEN_KID_MISMATCH`	`kid` not pinned / not a known tenant key
`TOKEN_TENANT_MISMATCH`	Token tenant ≠ expected tenant
`TOKEN_ADAPTER_MISMATCH`	Token adapter/target ≠ this action
`TOKEN_EXPIRED`	Past `expiresAt`
`TOKEN_TTL_EXCEEDS_LIMIT`	TTL beyond the 300s maximum
`TOKEN_CLAIMS_INVALID`	Claims fail schema validation

Info

The Ed25519 Authority Token described here is the token returned by POST /intent and verified by your service before it acts. Intended also uses an internal HMAC-signed permission token for some policy-pack flows; it is not the artifact downstream services verify, and it is not interchangeable with the Authority Token.

Authority Runtime Pipeline — where tokens are issued
Verify a Token — a step-by-step verification guide
Tenant Trust Boundary — per-tenant key isolation
Enforcement Lineage — how tokens link into the audit chain