Grant Token - Grantex

Overview

Grantex tokens are standard JWTs (RS256) extended with agent-specific claims. Any service can verify them locally using the published JWKS, without a per-token call to the Grantex verification API. Verifiers still need the public keys, fetched from the issuer and cached according to their SDK’s behavior.

Decoded Example

{
  "iss": "https://grantex.dev",
  "sub": "user_abc123",
  "agt": "did:grantex:ag_01HXYZ123abc",
  "dev": "org_yourcompany",
  "scp": ["calendar:read", "payments:initiate:max_500"],
  "iat": 1709000000,
  "exp": 1709086400,
  "jti": "tok_01HXYZ987xyz",
  "grnt": "grnt_01HXYZ456def"
}

Standard Claims

Claim	Type	Description
`iss`	`string`	Issuer — the Grantex server that signed the token
`sub`	`string`	The end-user (principal) who authorized this agent
`iat`	`number`	Issued-at timestamp (seconds since epoch)
`exp`	`number`	Expiry timestamp (seconds since epoch)
`jti`	`string`	Unique token ID — used for real-time revocation

Grantex-Specific Claims

Claim	Type	Description
`agt`	`string`	The agent’s DID — cryptographically verifiable identity
`dev`	`string`	The developer org that built the agent
`scp`	`string[]`	Exact scopes granted — services should check these
`grnt`	`string`	Grant record ID — links token to the persisted grant
`aud`	`string?`	Intended audience (optional) — services should reject tokens with a mismatched `aud`

The hosted service publishes keys at https://api.grantex.dev/.well-known/jwks.json, but its canonical iss value is https://grantex.dev. Current SDKs recognize that stable JWKS alias automatically. Custom verifiers must validate the canonical issuer explicitly.

Delegation Claims

Present on tokens issued to sub-agents via grants.delegate():

Claim	Type	Description
`parentAgt`	`string`	DID of the parent agent that spawned this sub-agent
`parentGrnt`	`string`	Grant ID of the parent grant — full delegation chain is traceable
`delegationDepth`	`number`	How many hops from the root grant (root = 0)

Verification

Grant tokens can be verified two ways:

Offline (recommended)

Verify the RS256 signature locally using the published JWKS. This avoids the online token-verification API, although the verifier may still need to retrieve the current public keys from the JWKS endpoint.

import { verifyGrantToken } from '@grantex/sdk';

const grant = await verifyGrantToken(token, {
  jwksUri: 'https://api.grantex.dev/.well-known/jwks.json',
  requiredScopes: ['calendar:read'],
});

from grantex import verify_grant_token, VerifyGrantTokenOptions

grant = verify_grant_token(token, VerifyGrantTokenOptions(
    jwks_uri="https://api.grantex.dev/.well-known/jwks.json",
))

Online

Call the Grantex API for real-time revocation status:

const result = await grantex.tokens.verify(token);
console.log(result.valid);   // true or false
console.log(result.scopes);

result = client.tokens.verify(token)
print(result.valid)
print(result.scopes)

Security

Algorithm pinning: RS256 is hardcoded in all three verification layers (auth service, TypeScript SDK, Python SDK). The alg header in the token cannot override this.
Replay prevention: Every token’s jti is tracked. Presenting a previously-seen jti returns valid: false.
Minimum key size: The auth service enforces a minimum 2048-bit RSA modulus on all signing keys.

Last modified on July 11, 2026

How It Works Scopes

​Overview

​Decoded Example

​Standard Claims

​Grantex-Specific Claims

​Delegation Claims

​Verification

​Offline (recommended)

​Online

​Security