Verify a Token

Verify authority decision tokens using tenant public keys and the verification gateway.

beginner2 min readimplemented

Verify a Token#

Intended tokens must be verified before any downstream action is executed.

1) Fetch Tenant Public Keys#

GET/tenants/:tenantId/authority-keys/publicRequires auth

Returns active/previous RS256 verification keys for a tenant.

bash

curl "https://api.intended.so/tenants/tenant_acme_prod/authority-keys/public" \
  -H "Authorization: Bearer mrt_live_abc123"

Use the token header kid to select the matching publicKeyPem.

2) Verify Through Gateway#

POST/verify/tokenRequires auth

tokenstring*Authority decision token (JWT).

publicKeyPemstring*Tenant public key PEM matching token kid.

expectedKidstringExpected key id for strict matching.

expectedTenantIdstringTenant assertion for verification context.

expectedAdapterIdstringAssert adapter binding in claims.

bash

curl -X POST https://api.intended.so/verify/token \
  -H "Authorization: Bearer mrt_live_abc123" \
  -H "x-tenant-id: tenant_acme_prod" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImtleS0xIn0...",
    "publicKeyPem": "-----BEGIN PUBLIC KEY-----...",
    "expectedKid": "key-1",
    "expectedTenantId": "tenant_acme_prod"
  }'

Response Example#

json

{
  "protocolVersion": "meritt.authority.v1",
  "verificationModel": "deterministic-rs256-hash-chain",
  "valid": true,
  "reason": null,
  "claims": {
    "intentId": "8aa3f5f6-b1a9-4c5b-a29f-b489f7d0be58",
    "tenantId": "tenant_acme_prod",
    "decision": "APPROVED"
  },
  "header": {
    "alg": "RS256",
    "kid": "key-1"
  }
}

3) Enforce Outcome#

valid=true and expected claims match: allow execution path.
valid=false: deny execution and re-evaluate via /intent if needed.

Common Failures#

Error	Meaning	Action
`VERIFY_KEY_NOT_FOUND`	`expectedKid` not registered for tenant	Refresh keys and retry with correct key
`VERIFY_PUBLIC_KEY_MISMATCH`	Wrong public key used	Use key returned by `/tenants/:tenantId/authority-keys/public`
`VERIFY_TENANT_REQUIRED`	Missing tenant verification context	Send `x-tenant-id` and/or `expectedTenantId`