Verify Authority Tokens#

The authorityDecisionToken returned by POST /intent is an Ed25519 JWT bound to exactly one intent, tenant, and target. Intended decides and signs; it never runs the action. Before your agent's action takes effect, the service that receives it (or the gateway you run in front of it) verifies the token locally — it never needs to call back to the Intended runtime. Verification is fail-closed: any failed check rejects the action.

This page uses @intended/verify's verifyToken, which is built on jose↗. Single-use enforcement (nonce consumption) is the verifying service's job; the last step below covers it.

Minted on APPROVED, verified locally, consumed once. Kid mismatch, bad signature, claim mismatch, and expiry are all rejected.

Token claims#

The validated claim set (from AuthorityDecisionTokenClaimsSchema):

At signing time the runtime also sets the registered JWT claims iss: "intended-authority", aud: <adapterId>, and integer iat / exp. The header is { "alg": "EdDSA", "typ": "JWT", "kid": "<tenant-key-id>" } — kid is mandatory.

Local verification flow#

With the TypeScript SDK#

From @intended-inc/sdk 0.8.0, guard() does all of this for you before your callback runs: it fetches the tenant's public key for the token's kid, calls POST /verify/token with consume: true, and runs the callback only if that call used the token up. A token that is invalid, expired or already used returns status: "denied" and the callback does not run. Pass { verifyToken: "verify" } to check without consuming (when a downstream service consumes the token), or "off" to skip the check, which logs a warning because the decision is then advisory only. This is a breaking change in 0.8.0: if your callback passes the token to a service that consumes it, use { verifyToken: "verify" }.

Checking a token needs intent:create or token:read (the "Write" preset has both; "Read" has token:read), verify:token or audit:read. Consuming it (consume: true) needs intent:create (the "Write" preset); any other key, including one with verify:token, gets 403 MISSING_CONSUME_SCOPE. Re-consuming a token with the same API key that submitted it answers TOKEN_ALREADY_CONSUMED but is not treated as a token replay by Intended's abuse detection.

/verify/* is rate limited to 600 requests per API key per 5 minutes by default (429 VERIFY_RATE_LIMITED with Retry-After).

The console's Insights page shows the share of allowed actions in the last 7 days whose token was verified with consume: true. Tokens checked only offline are not counted there.

Each credential gets a share of the tenant's /verify/* rate window, so one busy or misbehaving verifier is refused on its own (VERIFY_RATE_LIMITED) without blocking your other verifiers. VERIFY_TENANT_RATE_LIMITED means several credentials together filled the tenant window; Intended is alerted when that happens.

Verifying in code#

verifyToken returns { valid, reason, claims, header }. On success reason is null and claims is the validated claim set; on failure valid is false and reason names the failure.

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

const result = await verifyToken({
  token,                          // the authorityDecisionToken from POST /intent
  publicKeyPem,                   // tenant public key (SPKI PEM) for the token's kid
  expectedKid: kid,               // pin the key id
  expectedTenantId: "tenant_acme_prod",
  expectedAdapterId: "decision-only",
  expectedIssuer: "intended-authority",
  expectedAudience: "decision-only", // aud === adapterId
  maxTokenTtlSeconds: 300,        // 300s is the hard cap; a longer TTL is rejected
  clockSkewSeconds: 60,
});

if (!result.valid) {
  // result.reason is one of the documented failure reasons below
  throw new Error(result.reason ?? "TOKEN_SIGNATURE_INVALID");
}
// result.claims is the validated claim set; proceed with the action.

Failure reasons#

These are the exact reason values verifyToken returns. Treat every one as a hard reject.

On-robot verification (Physical AI)#

For physical-AI runtimes, the Authority Token minted by POST /v1/physical/authority-tokens is verified at the robot or controller before actuation lands, so a compromised network path or stale cloud session cannot let an actuation through. The physical-AI signer signs with RS256, not the Ed25519 used by the general /intent token above, and publishes its public key at /.well-known/jwks.json. In production, when INTENDED_PHYSICAL_KMS_KEY_ID is set, the signer is backed by a persistent AWS KMS key; in dev/sandbox it falls back to an ephemeral per-process keypair that rotates on restart, so cache JWKS short and refresh on a kid miss.

Any standard JWT library can verify a physical token. Check:

import jwt  # PyJWT[crypto]

jwks = jwt.PyJWKClient("https://api.intended.so/.well-known/jwks.json", cache_keys=True)

def verify_physical_token(token: str, tenant_id: str, actor_identity: str) -> dict | None:
    try:
        key = jwks.get_signing_key_from_jwt(token)
        claims = jwt.decode(
            token,
            key.key,
            algorithms=["RS256"],
            audience="intended-edge-verifier",
            issuer="https://api.intended.so",
            leeway=1,
            options={"require": ["exp", "jti", "sub"]},
        )
    except jwt.PyJWTError:
        return None  # refuse the actuation
    physical = claims.get("intended", {})
    if physical.get("tenantId") != tenant_id or claims["sub"] != actor_identity:
        return None
    return claims  # proceed with motion; record claims["jti"] if enforcing single use

Next steps#

• Authority Token Model — full structure, keys, and lifetime.
• Verify a Token (Guide) — the hosted endpoint, library and CLI side by side.
• Enforcement SDK — the SDK method reference.
• Error Patterns — runtime error codes. </content>