Grants

Manage grants, delegate authorization to sub-agents, and verify tokens via the API.

Overview

The grants sub-client provides operations on grant records: retrieving, listing, revoking, delegating to sub-agents, and verifying grant tokens online.

const grant = await grantex.grants.get('grnt_01HXYZ...');
console.log(grant.scopes);  // ['calendar:read', 'payments:initiate:max_500']
console.log(grant.status);  // 'active'

---

grants.get()

Retrieve a single grant by its ID.

const grant = await grantex.grants.get('grnt_01HXYZ...');

console.log(grant.id);          // 'grnt_01HXYZ...'
console.log(grant.agentId);     // 'ag_01HXYZ...'
console.log(grant.principalId); // 'user_abc123'
console.log(grant.scopes);      // ['calendar:read']
console.log(grant.status);      // 'active'
console.log(grant.expiresAt);   // '2026-03-02T12:00:00Z'

Parameters

grantId · string · required

The grant ID to retrieve.

Response: Grant

id · string

Unique grant identifier.

agentId · string

The agent that holds this grant.

agentDid · string

The agent’s decentralized identifier.

principalId · string

The user who authorized the grant.

developerId · string

The developer organization.

scopes · string[]

Granted scopes.

status · string

Grant status: 'active', 'revoked', or 'expired'.

issuedAt · string

ISO 8601 timestamp when the grant was issued.

expiresAt · string

ISO 8601 timestamp when the grant expires.

revokedAt · string

ISO 8601 timestamp when the grant was revoked (only present if status is 'revoked').

---

grants.list()

List grants with optional filters.

const result = await grantex.grants.list({
  agentId: 'ag_01HXYZ...',
  status: 'active',
  page: 1,
  pageSize: 25,
});

console.log(result.grants.length);  // grants returned on this page
for (const grant of result.grants) {
  console.log(`${grant.id}: ${grant.scopes.join(', ')}`);
}

Parameters

agentId · string

Filter by agent ID.

principalId · string

Filter by principal (user) ID.

status · string

Filter by status: 'active', 'revoked', or 'expired'.

page · number

Page number (1-indexed).

pageSize · number

Number of grants per page.

Response: ListGrantsResponse

grants · Grant[]

Array of grant objects.

total · number

Total number of grants matching the filters.

page · number

Current page number.

pageSize · number

Number of grants per page.

---

grants.revoke()

Revoke a grant by its ID. This immediately invalidates the grant and any associated tokens.

await grantex.grants.revoke('grnt_01HXYZ...');
// Returns void -- the grant is now revoked

Parameters

grantId · string · required

The grant ID to revoke.

Response

Returns void.

---

grants.delegate()

Create a delegated grant for a sub-agent. This implements the delegation chain described in SPEC section 9.

The parent agent passes its grant token, and the sub-agent receives a new grant token with scopes that are a subset of the parent’s.

const delegated = await grantex.grants.delegate({
  parentGrantToken: parentToken,
  subAgentId: 'ag_sub_01HXYZ...',
  scopes: ['calendar:read'],      // must be subset of parent's scopes
  expiresIn: '1h',
});

console.log(delegated.grantToken); // New RS256 JWT for the sub-agent
console.log(delegated.grantId);    // 'grnt_delegated_01HXYZ...'
console.log(delegated.scopes);     // ['calendar:read']
console.log(delegated.expiresAt);  // '2026-02-28T13:00:00Z'

Parameters

parentGrantToken · string · required

The parent agent’s grant token JWT.

subAgentId · string · required

The ID of the sub-agent to delegate to.

scopes · string[] · required

The scopes to delegate. Must be a subset of the parent grant’s scopes.

expiresIn · string

Duration for the delegated grant (e.g. '1h', '30m'). Cannot exceed the parent grant’s remaining lifetime.

Response

grantToken · string

The delegated grant token (RS256 JWT) for the sub-agent.

grantId · string

The delegated grant’s record ID.

scopes · string[]

The delegated scopes.

expiresAt · string

ISO 8601 expiry timestamp.

---

grants.verify()

Verify a grant token online and return a VerifiedGrant with full claim details. The SDK uses the server-verified claims returned by POST /v1/grants/verify — it does not decode the caller-supplied token locally, so forged or tampered tokens are always rejected by the server before any claim is surfaced.

const verified = await grantex.grants.verify(grantToken);

console.log(verified.tokenId);       // 'tok_01HXYZ...'
console.log(verified.grantId);       // 'grnt_01HXYZ...'
console.log(verified.principalId);   // 'user_abc123'
console.log(verified.agentDid);      // 'did:grantex:ag_01HXYZ...'
console.log(verified.scopes);        // ['calendar:read']
console.log(verified.delegationDepth); // 0 (root grant) or 1+ (delegated)

Parameters

token · string · required

The grant token JWT to verify.

Response: VerifiedGrant

Returns a VerifiedGrant object with all decoded claims. See Offline Verification for the full field reference.