AI Agent Authorization Guide for 2026: Scopes, Consent, and Revocation

npm install @grantex/sdk@0.3.13
python -m pip install grantex==0.3.14

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

const gx = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });
const principalId = 'user_alice';

const agent = await gx.agents.register({
  name: 'expense-report-agent',
  description: 'Reads receipts and creates expense reports after approval',
  scopes: ['tool:expense-api:read', 'tool:expense-api:write'],
});

const auth = await gx.authorize({
  agentId: agent.id,
  userId: principalId,
  scopes: ['tool:expense-api:read', 'tool:expense-api:write'],
  redirectUri: 'https://app.example.com/auth/callback',
});

console.log('Send the principal to: ' + auth.consentUrl);

// Call this from the registered callback after reading its code parameter.
export async function finishAuthorization(code: string) {
  const token = await gx.tokens.exchange({ code, agentId: agent.id });

  const localGrant = await verifyGrantToken(token.grantToken, {
    jwksUri: 'https://api.grantex.dev/.well-known/jwks.json',
    requiredScopes: ['tool:expense-api:write'],
  });

  // Online verification checks current server-side grant state.
  const currentGrant = await gx.grants.verify(token.grantToken);

  return { token, localGrant, currentGrant };
}

import os

from grantex import (
    AuthorizeParams,
    ExchangeTokenParams,
    Grantex,
    VerifyGrantTokenOptions,
    verify_grant_token,
)

client = Grantex(api_key=os.environ["GRANTEX_API_KEY"])
principal_id = "user_alice"

agent = client.agents.register(
    name="expense-report-agent",
    description="Reads receipts and creates expense reports after approval",
    scopes=["tool:expense-api:read", "tool:expense-api:write"],
)

auth = client.authorize(AuthorizeParams(
    agent_id=agent.id,
    user_id=principal_id,
    scopes=["tool:expense-api:read", "tool:expense-api:write"],
    redirect_uri="https://app.example.com/auth/callback",
))

print(f"Send the principal to: {auth.consent_url}")

# Call this from the registered callback after reading its code parameter.
def finish_authorization(code: str):
    token = client.tokens.exchange(ExchangeTokenParams(
        code=code,
        agent_id=agent.id,
    ))

    local_grant = verify_grant_token(
        token.grant_token,
        VerifyGrantTokenOptions(
            jwks_uri="https://api.grantex.dev/.well-known/jwks.json",
            required_scopes=["tool:expense-api:write"],
        ),
    )

    current_grant = client.grants.verify(token.grant_token)
    return token, local_grant, current_grant

import { Permission, ToolManifest } from '@grantex/sdk';

gx.loadManifest(new ToolManifest({
  connector: 'expense-api',
  description: 'Internal expense service',
  tools: {
    read_receipt: Permission.READ,
    create_report: Permission.WRITE,
  },
}));

// Obtain token from finishAuthorization() above.
await gx.grants.verify(token.grantToken); // current-state check

const decision = await gx.enforce({
  grantToken: token.grantToken,
  connector: 'expense-api',
  tool: 'create_report',
});

if (!decision.allowed) {
  throw new Error(decision.reason);
}

// Call the expense API only after the decision is allowed.
// After the action completes, explicitly record the outcome if desired:
await gx.audit.log({
  agentId: agent.id,
  agentDid: agent.did,
  grantId: token.grantId,
  principalId,
  action: 'expense-api.create_report',
  status: 'success',
});

await gx.grants.revoke(token.grantId);