Offline Verification

Overview

verifyGrantToken() is a standalone function that verifies signatures and claims locally after retrieving the published JWKS (JSON Web Key Set). It validates the RS256 signature, issuer, expiry, and optional scopes and audience. The current standalone helper resolves the remote JWKS on each invocation, so it is not a network-free hot path. Use it when signature-and-claim validation without a revocation lookup is the right trade-off. It avoids POST /v1/tokens/verify, but the JWKS endpoint must be reachable for each standalone helper call.

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

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

console.log(grant.principalId); // The user who authorized this agent
console.log(grant.agentDid);    // The agent's DID
console.log(grant.scopes);      // All granted scopes

The standalone helper may contact the JWKS endpoint when it resolves keys. Keep that endpoint reachable from the verifying service; token validation itself is performed locally and does not call POST /v1/tokens/verify.

Hosted tokens use the canonical issuer https://grantex.dev, even though the stable JWKS URL is served from https://api.grantex.dev. The SDK handles this alias automatically. For self-hosted deployments, it derives the expected issuer from the JWKS URL unless you set issuer or issuerDid explicitly.

Import

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

This function does not require a Grantex client instance.

Parameters

token

string

required

The grant token JWT string to verify.

options

VerifyGrantTokenOptions

required

Verification options.

VerifyGrantTokenOptions

jwksUri

string

required

The JWKS endpoint URL. For the hosted service, use https://api.grantex.dev/.well-known/jwks.json.

requiredScopes

string[]

If provided, the function throws GrantexTokenError when the token is missing any of these scopes.

audience

string

Expected aud claim. If provided, verification fails when the token’s audience does not match.

issuer

string

Expected iss claim. The hosted JWKS alias automatically expects https://grantex.dev; custom JWKS URLs derive the issuer from their URL when this option is omitted.

issuerDid

string

A did:web issuer identifier. When provided, the SDK derives both the JWKS URL and expected issuer from the DID. An explicit issuer still takes precedence.

clockTolerance

number

Optional clock-skew tolerance, in seconds, for time-based JWT claims.

Response: `VerifiedGrant`

tokenId

string

Unique token ID (the jti JWT claim).

grantId

string

The grant record ID (from the grnt claim, falls back to jti).

principalId

string

The end-user who authorized the agent (the sub claim).

agentDid

string

The agent’s decentralized identifier (the agt claim).

developerId

string

The developer organization that owns the agent (the dev claim).

scopes

string[]

The scopes granted to the agent (the scp claim).

issuedAt

number

Token issued-at timestamp in seconds since the Unix epoch.

expiresAt

number

Token expiry timestamp in seconds since the Unix epoch.

parentAgentDid

string

The parent agent’s DID, present only for delegated grants.

parentGrantId

string

The parent grant ID, present only for delegated grants.

delegationDepth

number

The delegation depth (0 = root grant, 1 = first-level delegation, etc.). Present only for delegated grants.

Error handling

verifyGrantToken() throws GrantexTokenError in the following cases:

The JWT signature is invalid
The token has expired
The token issuer does not match the expected issuer
Required claims (jti, sub, agt, dev, scp, iat, exp) are missing
The token is missing one or more requiredScopes
The audience does not match

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

try {
  const grant = await verifyGrantToken(token, {
    jwksUri: 'https://api.grantex.dev/.well-known/jwks.json',
    requiredScopes: ['payments:initiate'],
  });
  // Token is valid -- proceed
} catch (err) {
  if (err instanceof GrantexTokenError) {
    console.error('Token verification failed:', err.message);
    // e.g. "Grant token is missing required scopes: payments:initiate"
  }
}

JWT claims mapping

The following table shows how JWT claims map to VerifiedGrant fields:

JWT Claim	VerifiedGrant Field	Description
`jti`	`tokenId`	Unique token identifier
`grnt`	`grantId`	Grant record ID (falls back to `jti`)
`sub`	`principalId`	End-user identifier
`agt`	`agentDid`	Agent decentralized identifier
`dev`	`developerId`	Developer organization ID
`scp`	`scopes`	Granted scopes array
`iat`	`issuedAt`	Issued-at timestamp (epoch seconds)
`exp`	`expiresAt`	Expiry timestamp (epoch seconds)
`parentAgt`	`parentAgentDid`	Parent agent DID (delegation)
`parentGrnt`	`parentGrantId`	Parent grant ID (delegation)
`delegationDepth`	`delegationDepth`	Delegation chain depth

Comparison with online verification

	`verifyGrantToken()`	`tokens.verify()`
Network call	May fetch keys from the JWKS endpoint	Calls Grantex API
Latency	Local cryptography plus JWKS retrieval when needed	Network round-trip
Revocation check	No (checks signature + expiry only)	Yes (checks revocation status)
Requires API key	No	Yes
Use case	Services verifying tokens at high throughput	Admin dashboards, token status checks

​Overview

​Import

​Parameters

​VerifyGrantTokenOptions

​Response: VerifiedGrant

​Error handling

​JWT claims mapping

​Comparison with online verification

Overview

Import

Parameters

VerifyGrantTokenOptions

Response: `VerifiedGrant`

Error handling

JWT claims mapping

Comparison with online verification