Grantex

Enterprise SSO

Grantex provides OIDC and SAML 2.0 enterprise SSO with multiple identity-provider connections, email-domain routing, enforcement, JIT provisioning, and group-to-scope mapping from identity-provider claims. The LDAP surface is a direct-bind preview: it authenticates a supplied directory identity but does not search directories or retrieve LDAP groups.

Key capabilities:

• Multi-IdP connections - Configure multiple OIDC and SAML 2.0 identity providers per organization; LDAP connection records support the direct-bind preview
• OIDC Discovery + JWKS verification — Automatic endpoint discovery and cryptographic ID token verification
• SAML 2.0 — Full SAML response parsing with certificate-based signature verification
• LDAP / Active Directory preview - Direct-bind authentication only; directory search and LDAP group retrieval are not implemented
• Domain-based routing — Automatically route users to the correct IdP based on their email domain
• JIT provisioning — Auto-create or update principals on first SSO login
• Group-to-scope mapping - Map OIDC or SAML group/role claims to Grantex scopes; this does not retrieve LDAP groups
• SSO enforcement — Require SSO authentication for all users in an organization
• Session management — Track, list, and revoke active SSO sessions

TypeScript

// Create an OIDC connection
const conn = await grantex.sso.createConnection({
  name: 'Okta Production',
  protocol: 'oidc',
  issuerUrl: 'https://mycompany.okta.com',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  domains: ['mycompany.com'],
  jitProvisioning: true,
  groupAttribute: 'groups',
  groupMappings: { Engineering: ['read', 'write', 'deploy'], Admins: ['admin'] },
  defaultScopes: ['read'],
});

// Create a SAML 2.0 connection
await grantex.sso.createConnection({
  name: 'Azure AD SAML',
  protocol: 'saml',
  idpEntityId: 'https://sts.windows.net/tenant-id/',
  idpSsoUrl: 'https://login.microsoftonline.com/tenant-id/saml2',
  idpCertificate: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----',
  spEntityId: 'urn:grantex:mycompany',
  spAcsUrl: 'https://myapp.com/sso/callback/saml',
  domains: ['mycompany.com'],
});

// Enforce SSO for the organization
await grantex.sso.setEnforcement({ enforce: true });

// Handle OIDC callback with verified ID token
const result = await grantex.sso.handleOidcCallback({ code, state });
console.log(result.email, result.mappedScopes, result.sessionId);

// List and revoke sessions
const { sessions } = await grantex.sso.listSessions();
await grantex.sso.revokeSession(sessions[0].id);

Python

# Create an OIDC connection
conn = client.sso.create_connection(CreateSsoConnectionParams(
    name="Okta Production",
    protocol="oidc",
    issuer_url="https://mycompany.okta.com",
    client_id="your-client-id",
    client_secret="your-client-secret",
    domains=["mycompany.com"],
    jit_provisioning=True,
    group_attribute="groups",
    group_mappings={"Engineering": ["read", "write", "deploy"]},
))

# Handle OIDC callback
result = client.sso.handle_oidc_callback(SsoOidcCallbackParams(code=code, state=state))
print(result.email, result.mapped_scopes, result.session_id)

CLI

# Create a connection
grantex sso connections create --name "Okta" --protocol oidc \
  --issuer-url https://mycompany.okta.com \
  --client-id $CLIENT_ID --client-secret $CLIENT_SECRET \
  --domains mycompany.com --jit-provisioning

# List connections
grantex sso connections list

# Test connectivity
grantex sso connections test sso_01HXYZ...

# Enforce SSO
grantex sso enforce --enable

FIDO2 / WebAuthn

Grantex supports passkey-based human presence verification using the FIDO2/WebAuthn standard. When enabled, end-users prove they are physically present during the consent flow by authenticating with a passkey (biometric, security key, or platform authenticator). This raises the assurance level of every grant from "user clicked approve" to "user was cryptographically verified."

How It Works

1. Developer enables FIDO — Set fidoRequired: true on your developer profile via PATCH /v1/me
2. User registers a passkey — During the first consent flow, the user registers a FIDO2 credential (fingerprint, Face ID, YubiKey, etc.)
3. User authenticates on consent — On subsequent authorization requests, the user completes a WebAuthn assertion challenge instead of a simple button click
4. FIDO evidence embedded in grants — The assertion result is recorded in the grant and can be embedded in Verifiable Credentials as cryptographic proof of human presence

SDK Usage

// Enable FIDO for your developer account
await grantex.updateSettings({ fidoRequired: true, fidoRpName: 'My App' });

// Register a passkey for an end-user (called from the browser)
const options = await grantex.webauthn.registerOptions({ principalId: 'user_abc123' });
// Pass options to navigator.credentials.create() in the browser
const credential = await navigator.credentials.create({ publicKey: options });
await grantex.webauthn.registerVerify({ challengeId: options.challengeId, response: credential });

// List and manage credentials
const creds = await grantex.webauthn.listCredentials('user_abc123');
await grantex.webauthn.deleteCredential(credentialId);

# Enable FIDO for your developer account
from grantex import UpdateDeveloperSettingsParams, WebAuthnRegistrationVerifyParams

client.update_settings(UpdateDeveloperSettingsParams(
    fido_required=True,
    fido_rp_name="My App",
))

# Register a passkey (server-side portion)
options = client.webauthn.register_options(principal_id="user_abc123")
# Browser performs navigator.credentials.create() and sends response back
result = client.webauthn.register_verify(WebAuthnRegistrationVerifyParams(
    challenge_id=options.challenge_id,
    response=credential_response,
))

# List and manage credentials
creds = client.webauthn.list_credentials("user_abc123")
client.webauthn.delete_credential(credential_id)

WebAuthn API Endpoints

Verifiable Credentials

Grantex can issue W3C Verifiable Credentials (VCs) alongside standard JWTs. While JWTs are optimized for real-time authorization, VCs provide a portable, tamper-evident, standards-based proof of authorization that can be presented to any verifier — including systems outside the Grantex ecosystem.

Why VCs Matter for Agents

In agentic commerce, an agent acting on your behalf needs to prove its authorization to third-party services that may not integrate with Grantex directly. A Verifiable Credential is a self-contained, cryptographically signed document that any party can verify using the issuer's published DID document — no API calls, no accounts, no trust relationships required.

How It Works

When exchanging an authorization code for a grant token, pass credentialFormat: "vc-jwt" to receive a Verifiable Credential alongside the standard grant token:

const result = await grantex.tokens.exchange({
  code,
  agentId: agent.id,
  credentialFormat: 'vc-jwt',   // opt-in to VC issuance
});

console.log(result.grantToken);         // standard RS256 JWT (unchanged)
console.log(result.verifiableCredential); // W3C VC-JWT

result = client.tokens.exchange(ExchangeTokenParams(
    code=code,
    agent_id=agent.id,
    credential_format="vc-jwt",
))

print(result.verifiable_credential)  # W3C VC-JWT

Credential Types

Verifying a VC

const verification = await grantex.credentials.verify(vcJwt);
console.log(verification.valid);
console.log(verification.credentialSubject);
console.log(verification.issuer); // "did:web:grantex.dev"

verification = client.credentials.verify(vc_jwt)
print(verification.valid)
print(verification.credential_subject)

Revocation via StatusList2021

Grantex implements the W3C StatusList2021 revocation mechanism. Each credential references a status list entry. When a grant is revoked, the corresponding bit in the status list is flipped, and any verifier checking the credential sees it as revoked.

// Check a specific credential's status
const cred = await grantex.credentials.get(credentialId);
console.log(cred.status); // "active" or "revoked"

// List credentials with filters
const { credentials } = await grantex.credentials.list({
  grantId: 'grnt_01HXYZ...',
  status: 'active',
});

FIDO Evidence in VCs

When FIDO is enabled and the user completes a WebAuthn assertion during consent, the VC includes a fidoEvidence field that cryptographically proves human presence at the time of authorization. This is compatible with the Mastercard Verifiable Intent specification for agentic commerce.

DID Infrastructure

Grantex publishes a W3C DID document at /.well-known/did.json (did:web:grantex.dev). This document contains the public keys used to sign Verifiable Credentials, enabling any party to verify credentials without contacting Grantex:

curl https://api.grantex.dev/.well-known/did.json

Verifiable Credentials API Endpoints

MPP Agent Identity

MPP (Machine Payments Protocol) defines HTTP 402 payment flows for software clients. Grantex can attach an AgentPassportCredential based on W3C Verifiable Credentials 2.0 so a configured merchant can verify agent, principal, category, amount-limit, expiry, and delegation claims after obtaining the issuer keys and current status data. The credential carries authorization context; it does not prove that a payment settled, an order was approved, or a provider accepted the transaction.

Why Agent Passports?

A wallet or payment-source identifier may not tell a merchant which internal agent is acting, which principal delegated authority, or which policy limits apply. An agent passport can supply that context when both sides integrate and enforce it.

The current Grantex passport shape uses Ed25519 signatures, a W3C VC 2.0 data model, configured purchase categories, transaction ceilings, expiry, delegation context, and StatusList2021-style status data. A relying merchant must still validate the issuer, refresh keys and status according to its risk policy, enforce the claims at the protected action, and run its own payment, fraud, sanctions, order, and settlement controls.

How It Works

Verification boundary: cached keys can support local signature checks after retrieval. Current revocation requires refreshed status data, and cache policy determines how quickly a relying service observes a change.

Credential Structure

Issue a Passport

TypeScript:

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

const grantex = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });

const passport = await grantex.passports.issue({
  agentId: 'ag_01HXYZ...',
  grantId: 'grnt_01HXYZ...',
  allowedMPPCategories: ['inference', 'compute'],
  maxTransactionAmount: { amount: 50, currency: 'USDC' },
  paymentRails: ['tempo'],
  expiresIn: '24h',
});
// passport.passportId   → "urn:grantex:passport:01HXYZ..."
// passport.encodedCredential → base64url for X-Grantex-Passport header

cURL:

curl -X POST https://api.grantex.dev/v1/passport/issue \
  -H "Authorization: Bearer $GRANTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "ag_01HXYZ...",
    "grantId": "grnt_01HXYZ...",
    "allowedMPPCategories": ["inference", "compute"],
    "maxTransactionAmount": { "amount": 50, "currency": "USDC" },
    "expiresIn": "24h"
  }'

Attach to MPP Requests

import { createMppPassportMiddleware } from '@grantex/mpp';

const middleware = createMppPassportMiddleware({ passport });
const enrichedRequest = await middleware(new Request(url, init));
// enrichedRequest now has X-Grantex-Passport header
const response = await fetch(enrichedRequest);

Verify on the Merchant Side

Standalone verification:

import { verifyPassport } from '@grantex/mpp';

const verified = await verifyPassport(encodedCredential, {
  requiredCategories: ['inference'],
  maxAmount: 10,
});
// verified.humanDID        → "did:grantex:user_alice"
// verified.organizationDID → "did:web:acme.com"
// verified.allowedCategories → ["inference", "compute"]
// verified.maxTransactionAmount → { amount: 50, currency: "USDC" }

Express middleware (one-liner):

import { requireAgentPassport } from '@grantex/mpp';

app.use('/api/inference', requireAgentPassport({
  requiredCategories: ['inference'],
  maxAmount: 10,
}));
// req.agentPassport is populated on valid requests
// 403 with typed error code on invalid requests

Trust Registry

Query any organization's verified trust level — no authentication required:

curl https://api.grantex.dev/v1/trust-registry/did:web:grantex.dev
# {"organizationDID":"did:web:grantex.dev","trustLevel":"soc2","domains":["grantex.dev"]}

import { lookupOrgTrust } from '@grantex/mpp';

const record = await lookupOrgTrust('did:web:acme.com');
// record.trustLevel → "verified" | "soc2" | "basic"
// record.verificationMethod → "dns-txt" | "manual" | "soc2"

Revocation

Revoking a passport updates server-side status immediately. Local verifiers observe the change only after an online revocation check or status-data refresh, so cached results can lag:

await grantex.passports.revoke('urn:grantex:passport:01HXYZ...');
// Revocation-aware verification rejects after checking refreshed status data

Error Codes

MPP Agent Identity API Endpoints

See packages/mpp/ for full package docs. Demo: grantex.dev/mpp-demo.

SD-JWT Selective Disclosure

Grantex supports SD-JWT (Selective Disclosure JWT) for privacy-preserving credential presentation. While a standard VC-JWT reveals all claims to every verifier, SD-JWT lets the holder choose exactly which fields to disclose — keeping everything else hidden.

Why SD-JWT?

In agentic commerce, different verifiers need different levels of information. A payment processor needs to know the agent's scopes and budget, but not the principal's identity. A compliance auditor needs the principal and timestamps, but not the scopes. SD-JWT enables minimum-disclosure presentations that satisfy each verifier's requirements without over-sharing.

How It Works

When exchanging an authorization code, pass credentialFormat: "sd-jwt" to receive an SD-JWT credential:

const result = await grantex.tokens.exchange({
  code,
  agentId: agent.id,
  credentialFormat: 'sd-jwt',   // opt-in to SD-JWT issuance
});

console.log(result.grantToken);         // standard RS256 JWT (unchanged)
console.log(result.sdJwt);              // SD-JWT with selective disclosure

result = client.tokens.exchange(ExchangeTokenParams(
    code=code,
    agent_id=agent.id,
    credential_format="sd-jwt",
))

print(result.sd_jwt)  # SD-JWT with selective disclosure

Creating a Presentation

The holder selects which claims to disclose when presenting to a verifier:

const presentation = await grantex.credentials.present({
  sdJwt: result.sdJwt,
  disclosedClaims: ['scopes', 'agentId'],   // only reveal these fields
});

// Send presentation to the verifier — they see scopes and agentId,
// but principalId, developerId, grantId, etc. remain hidden

presentation = client.credentials.present(
    sd_jwt=result.sd_jwt,
    disclosed_claims=["scopes", "agent_id"],
)

SD-JWT Format

An SD-JWT consists of: <issuer-jwt>~<disclosure1>~<disclosure2>~...~

Each disclosure is a base64url-encoded JSON array [salt, claim-name, claim-value]. The verifier can only see claims for which a disclosure is provided.

Disclosable Claims

SD-JWT API Endpoints

Budget Controls

Grantex provides per-grant budget controls that let developers cap how much an agent can spend. Budget allocations are enforced atomically — if a debit would exceed the remaining balance, it fails with a 402 INSUFFICIENT_BUDGET error. Threshold alerts fire at 50% and 80% consumption, and the remaining budget is embedded in grant tokens via the bdg JWT claim.

// Allocate a budget to a grant
const budget = await grantex.budgets.allocate({
  grantId: 'grnt_01HXYZ...',
  amount: 1000,
  currency: 'USD',
});

// Debit against the budget
const debit = await grantex.budgets.debit({
  grantId: 'grnt_01HXYZ...',
  amount: 42.50,
  description: 'Flight booking',
});
console.log(debit.remaining); // 957.50

// Check the current balance
const balance = await grantex.budgets.balance('grnt_01HXYZ...');
console.log(balance.remainingBudget);

// List all budget transactions for a grant
const { transactions } = await grantex.budgets.transactions('grnt_01HXYZ...');

# Allocate a budget to a grant
budget = client.budgets.allocate(
    grant_id="grnt_01HXYZ...",
    amount=1000,
    currency="USD",
)

# Debit against the budget
debit = client.budgets.debit(
    grant_id="grnt_01HXYZ...",
    amount=42.50,
    description="Flight booking",
)
print(debit.remaining)  # 957.50

# Check the current balance
balance = client.budgets.balance("grnt_01HXYZ...")

# List all budget transactions
transactions = client.budgets.transactions("grnt_01HXYZ...")

Budget API Endpoints

Event Streaming

Grantex provides real-time event streaming via Server-Sent Events (SSE) and WebSocket. Subscribe to authorization lifecycle events as they happen — grant creation, revocation, token issuance, and budget threshold alerts. Events are published to both webhooks and streaming endpoints, so you can choose push or pull.

// SSE — async generator, automatically reconnects
for await (const event of grantex.events.stream()) {
  console.log(event.type);   // 'grant.created', 'token.issued', etc.
  console.log(event.data);
}

// Convenience wrapper with a callback
grantex.events.subscribe((event) => {
  if (event.type === 'budget.threshold') {
    alert(`Grant ${event.data.grantId} is at ${event.data.percentage}% budget`);
  }
});

# SSE — async generator
async for event in client.events.stream():
    print(event.type)   # 'grant.created', 'grant.revoked', etc.
    print(event.data)

# Convenience wrapper
async def handler(event):
    if event.type == "budget.exhausted":
        await revoke_grant(event.data["grant_id"])

await client.events.subscribe(handler)

Event Types

Event Streaming API Endpoints

Usage Metering

Grantex tracks API usage per developer — token exchanges, authorization requests, and verification calls. Use the metering API to monitor consumption, enforce plan limits, and export usage data for billing.

// Get current period usage
const usage = await grantex.usage.current();
console.log(usage.tokenExchanges);
console.log(usage.authorizations);
console.log(usage.totalRequests);

// Get usage history over the last 30 days
const { entries } = await grantex.usage.history({ days: 30 });
entries.forEach((e) => console.log(`${e.date}: ${e.totalRequests} requests`));

# Get current period usage
usage = client.usage.current()
print(usage.token_exchanges)
print(usage.total_requests)

# Get usage history over the last 30 days
history = client.usage.history(days=30)
for entry in history.entries:
    print(f"{entry.date}: {entry.total_requests} requests")

Usage Metering API Endpoints

Custom Domains

Grantex provides domain registration and DNS-based ownership verification so your account is provisioned and ready to host Grantex on your own domain. Today the API covers registration, verification, listing, and deletion; runtime traffic routing through verified domains (consent UI / API endpoints served from your domain) is on the roadmap and currently still served from *.grantex.dev. Track progress in issues.

// Register a custom domain
const domain = await grantex.domains.create({ domain: 'auth.yourapp.com' });
console.log(domain.verificationToken);
// → Add a DNS TXT record: _grantex-verify.auth.yourapp.com = <token>

// Verify the domain after adding the DNS record
const verified = await grantex.domains.verify(domain.id);
console.log(verified.verified); // true

// List all registered domains
const { domains } = await grantex.domains.list();

// Delete a domain
await grantex.domains.delete(domain.id);

# Register a custom domain
domain = client.domains.create(domain="auth.yourapp.com")
print(domain.verification_token)

# Verify after adding DNS TXT record
verified = client.domains.verify(domain.id)
print(verified.verified)  # True

# List all domains
domains = client.domains.list()

# Delete a domain
client.domains.delete(domain.id)

Custom Domains API Endpoints

Policy-as-Code

Grantex supports pluggable policy backends for fine-grained authorization decisions. In addition to the built-in policy engine, you can connect OPA (Open Policy Agent) or Cedar to evaluate authorization requests against externally managed policy bundles. Policy bundles can be synced via direct upload or triggered automatically from a git repository webhook.

// Upload a policy bundle
await grantex.policies.sync({
  format: 'opa',           // 'opa' or 'cedar'
  bundle: bundleBuffer,    // policy bundle as Buffer
});

// List policy bundles
const { bundles } = await grantex.policies.bundles();

# Upload a policy bundle
client.policies.sync(
    format="opa",
    bundle=bundle_bytes,
)

# List policy bundles
bundles = client.policies.bundles()

Supported Policy Backends

Policy-as-Code API Endpoints

DPDP Act 2023 Compliance

DPDP Act 2023 support includes structured consent records, purpose limitation, data principal rights workflows (access, erasure, grievance), and audit-ready exports. Available in all SDKs and the CLI. This is a technical control mapping, not a legal certification.

// Register a consent notice
const notice = await grantex.dpdp.createConsentNotice({
  noticeId: 'privacy-v1',
  version: '1.0',
  title: 'Data Processing Notice',
  content: 'We process your data for...',
  purposes: [{ code: 'analytics', description: 'Usage analytics' }],
});

// Create a consent record linked to a grant
const record = await grantex.dpdp.createConsentRecord({
  grantId: 'grnt_01HXYZ...',
  dataPrincipalId: 'user@example.com',
  purposes: [{ code: 'analytics', description: 'Usage analytics' }],
  consentNoticeId: 'privacy-v1',
  processingExpiresAt: '2027-01-01T00:00:00Z',
});

// Data principal exercises right to access (DPDP §11)
const { records } = await grantex.dpdp.listPrincipalRecords('user@example.com');

// Withdraw consent — optionally revoke grant and delete data
const withdrawal = await grantex.dpdp.withdrawConsent(record.recordId, {
  reason: 'No longer needed',
  revokeGrant: true,
  deleteProcessedData: true,
});

// File a grievance (DPDP §13(6))
const grievance = await grantex.dpdp.fileGrievance({
  dataPrincipalId: 'user@example.com',
  type: 'data_breach',
  description: 'Unauthorized data access',
});

// Request data erasure (DPDP §11)
const erasure = await grantex.dpdp.requestErasure('user@example.com');

// Generate compliance export
const report = await grantex.dpdp.createExport({
  type: 'dpdp-audit',
  dateFrom: '2026-01-01T00:00:00Z',
  dateTo: '2026-04-01T00:00:00Z',
});

View the full README on GitHub