Offline Verification

Verify grant tokens locally with published JWKS keys, without a per-token Grantex verification API call.

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