AI Agent Authorization Quickstart

npm install @grantex/sdk@0.3.13

python -m pip install grantex==0.3.14

go get github.com/mishrasanjeev/grantex-go@v0.1.10

npm install -g @grantex/cli
grantex config set --url https://api.grantex.dev --key YOUR_API_KEY

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

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

const agent = await grantex.agents.register({
  name: 'travel-booker',
  description: 'Books flights and hotels on behalf of users',
  scopes: ['calendar:read', 'payments:initiate:max_500', 'email:send'],
});

console.log(agent.did);
// → did:grantex:ag_01HXYZ123abc...

import os

from grantex import Grantex

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

agent = client.agents.register(
    name="travel-booker",
    scopes=["calendar:read", "payments:initiate:max_500", "email:send"],
    description="Books flights and hotels on behalf of users",
)

print(agent.did)
# → did:grantex:ag_01HXYZ123abc...

ctx := context.Background()
client := grantex.NewClient(os.Getenv("GRANTEX_API_KEY"))

agent, err := client.Agents.Register(ctx, grantex.RegisterAgentParams{
    Name:        "travel-booker",
    Description: "Books flights and hotels on behalf of users",
    Scopes:      []string{"calendar:read", "payments:initiate:max_500", "email:send"},
})
if err != nil {
    log.Fatal(err)
}

const didPrefix = "did:grantex:"
if !strings.HasPrefix(agent.DID, didPrefix) {
    log.Fatal("unexpected agent DID")
}
agentID := strings.TrimPrefix(agent.DID, didPrefix)
fmt.Printf("%s (%s)\n", agentID, agent.DID)

grantex agents register \
  --name travel-booker \
  --description "Books flights and hotels on behalf of users" \
  --scopes calendar:read,payments:initiate:max_500,email:send

const authRequest = await grantex.authorize({
  agentId: agent.id,
  userId: 'user_abc123',
  scopes: ['calendar:read', 'payments:initiate:max_500'],
  expiresIn: '24h',
  redirectUri: 'https://yourapp.com/auth/callback',
});

// Redirect user to the consent page
console.log(authRequest.consentUrl);
// → https://consent.grantex.dev/authorize?req=eyJ...

from grantex import AuthorizeParams

auth = client.authorize(AuthorizeParams(
    agent_id=agent.id,
    user_id="user_abc123",
    scopes=["calendar:read", "payments:initiate:max_500"],
))

# Redirect user to the consent page
print(auth.consent_url)

authRequest, err := client.Authorize(ctx, grantex.AuthorizeParams{
    AgentID:     agentID,
    PrincipalID: "user_abc123",
    Scopes:      []string{"calendar:read", "payments:initiate:max_500"},
    ExpiresIn:   "24h",
    RedirectURI: "https://yourapp.com/auth/callback",
})
if err != nil {
    log.Fatal(err)
}

// Redirect the user to the consent page.
fmt.Println(authRequest.ConsentURL)

grantex authorize \
  --agent ag_01HXYZ... \
  --principal user_abc123 \
  --scopes calendar:read,payments:initiate:max_500
# Sandbox mode returns the code directly

const token = await grantex.tokens.exchange({
  code,                  // from the redirect callback
  agentId: agent.id,
});

console.log(token.grantToken);  // RS256 JWT — pass this to your agent
console.log(token.scopes);      // ['calendar:read', 'payments:initiate:max_500']
console.log(token.grantId);     // 'grnt_01HXYZ...'

from grantex import ExchangeTokenParams

token = client.tokens.exchange(ExchangeTokenParams(
    code=code,
    agent_id=agent.id,
))

print(token.grant_token)  # RS256 JWT
print(token.scopes)       # ('calendar:read', 'payments:initiate:max_500')
print(token.grant_id)     # 'grnt_01HXYZ...'

token, err := client.Tokens.Exchange(ctx, grantex.ExchangeTokenParams{
    Code:    code, // from the redirect callback
    AgentID: agentID,
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(token.GrantToken)
fmt.Println(token.Scopes)
fmt.Println(token.GrantID)

grantex tokens exchange --code <code> --agent-id ag_01HXYZ...
# Returns grantToken (JWT), refreshToken, grantId, scopes

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

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

console.log(grant.principalId); // 'user_abc123'
console.log(grant.scopes);     // ['calendar:read', 'payments:initiate:max_500']

from grantex import verify_grant_token, VerifyGrantTokenOptions

grant = verify_grant_token(token.grant_token, VerifyGrantTokenOptions(
    jwks_uri="https://api.grantex.dev/.well-known/jwks.json",
))

print(grant.principal_id)  # 'user_abc123'
print(grant.scopes)        # ('calendar:read', 'payments:initiate:max_500')

grant, err := grantex.VerifyGrantToken(ctx, token.GrantToken, grantex.VerifyOptions{
    JwksURI:        "https://api.grantex.dev/.well-known/jwks.json",
    RequiredScopes: []string{"calendar:read"},
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(grant.PrincipalID) // "user_abc123"
fmt.Println(grant.Scopes)

grantex tokens verify <jwt>
# Shows: valid, grantId, scopes, principal, agent, expiresAt

await grantex.audit.log({
  agentId: agent.id,
  agentDid: agent.did,
  grantId: token.grantId,
  principalId: 'user_abc123',
  action: 'payment.initiated',
  status: 'success',
  metadata: { amount: 420, currency: 'USD', merchant: 'Air India' },
});

client.audit.log(
    agent_id=agent.id,
    agent_did=agent.did,
    grant_id=token.grant_id,
    principal_id="user_abc123",
    action="payment.initiated",
    status="success",
    metadata={"amount": 420, "currency": "USD", "merchant": "Air India"},
)

grantex audit log \
  --agent-id ag_01HXYZ... \
  --agent-did did:grantex:ag_01HXYZ... \
  --grant-id grnt_01HXYZ... \
  --principal-id user_abc123 \
  --action payment.initiated \
  --status success \
  --metadata '{"amount":420,"currency":"USD","merchant":"Air India"}'