Skip to main content

​
Overview

The passports sub-client manages AgentPassportCredentials — W3C VC 2.0 credentials that bind agent identity, human delegation, and spending limits for machine payment flows. 
const passport = await grantex.passports.issue({ ... });
const record   = await grantex.passports.get('urn:grantex:passport:01HXYZ...');
const result   = await grantex.passports.revoke('urn:grantex:passport:01HXYZ...');

​
passports.issue()

Issue a new AgentPassportCredential for an agent with an active grant. 
const passport = await grantex.passports.issue({
  agentId: 'ag_01HXYZ...',
  grantId: 'grnt_01HXYZ...',
  allowedMPPCategories: ['inference', 'compute'],
  maxTransactionAmount: { amount: 50, currency: 'USDC' },
  paymentRails: ['tempo'],
  expiresIn: '24h',
});

console.log(passport.passportId);        // "urn:grantex:passport:01HXYZ..."
console.log(passport.encodedCredential); // base64url for X-Grantex-Passport header
console.log(passport.expiresAt);         // "2026-03-21T03:13:48.150Z"

​
Parameters

​
agentId
string
required
Grantex agent ID (ag_...). Must belong to the developer.
​
grantId
string
required
Active Grantex grant ID (grnt_...). Must include payments:mpp:* scopes for each requested category.
​
allowedMPPCategories
string[]
required
MPP service categories: inference, compute, data, storage, search, media, delivery, browser, general.
​
maxTransactionAmount
object
required
Maximum per-transaction amount: { amount: number, currency: 'USDC' }.
​
paymentRails
string[]
default:"['tempo']"
Payment networks to include in the credential.
​
expiresIn
string
default:"24h"
Expiry duration (e.g., 1h, 8h, 24h, 30d). Maximum: 720h (30 days).
​
parentPassportId
string
For delegated sub-agent passports — links to the parent passport.

​
Response: IssuedPassportResponse

FieldTypeDescription
passportIdstringurn:grantex:passport:<ulid>
credentialobjectFull AgentPassportCredential JSON
encodedCredentialstringBase64url-encoded credential for headers
expiresAtstringISO 8601 expiry timestamp

​
Errors

CodeHTTPCause
INVALID_AGENT400Agent not found or not owned by developer
INVALID_GRANT400Grant not found, revoked, or not owned by agent
SCOPE_INSUFFICIENT400Grant doesn’t include required payments:mpp:* scopes
AMOUNT_EXCEEDS_BUDGET400Max amount exceeds remaining budget allocation
INVALID_EXPIRY422Expiry exceeds 720 hours

​
passports.get()

Retrieve a passport by its ID. Returns the full credential JSON plus current status. 
const record = await grantex.passports.get('urn:grantex:passport:01HXYZ...');

console.log(record.status); // "active" | "revoked" | "expired"

​
Parameters

​
passportId
string
required
The passport URN identifier.

​
passports.revoke()

Revoke a passport immediately. Flips the StatusList2021 bit so offline verifiers see the revocation. 
const result = await grantex.passports.revoke('urn:grantex:passport:01HXYZ...');

console.log(result.revoked);   // true
console.log(result.revokedAt); // "2026-03-20T03:14:15.261Z"

​
Parameters

​
passportId
string
required
The passport URN identifier.

​
Response: RevokePassportResponse

FieldTypeDescription
revokedbooleanAlways true on success
revokedAtstringISO 8601 revocation timestamp

​
passports.list()

List passports with optional filters. 
const passports = await grantex.passports.list({
  agentId: 'ag_01HXYZ...',
  status: 'active',
});

​
Parameters

​
agentId
string
Filter by agent ID.
​
grantId
string
Filter by grant ID.
​
status
string
Filter by status: active, revoked, or expired.