Authorization

Initiate the delegated authorization flow to request user consent for your agent.

Overview

The authorize() method starts the Grantex authorization flow. It creates an authorization request and returns a consent URL where the user can approve or deny the requested scopes.

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

// Redirect the user to the consent page
console.log(authRequest.consentUrl);

The userId parameter is mapped to principalId in the API request body. This is the identifier for the human user in your system.

Parameters

agentId · string · required

The ID of the agent requesting authorization (from agents.register()).

userId · string · required

Your application’s user identifier. Mapped to principalId in the protocol.

scopes · string[] · required

The scopes the agent is requesting. Must be a subset of the agent’s registered scopes.

audience · string

Intended token recipient. When set, the issued grant token includes this value in its aud claim; verifiers should require the same audience.

expiresIn · string

How long the grant should last (e.g. '1h', '24h', '7d'). Defaults to the server-configured maximum.

redirectUri · string

The URL to redirect the user to after they approve or deny the request. The authorization code will be appended as a query parameter.

codeChallenge · string

PKCE S256 code challenge. Use generatePkce() to create this value. See PKCE.

codeChallengeMethod · string

Must be 'S256' when codeChallenge is provided.

Response

The method returns an AuthorizationRequest object:

authRequestId · string

Unique identifier for this authorization request.

consentUrl · string

URL to redirect the user to for consent approval.

agentId · string

The agent that initiated the request.

principalId · string

The user identifier (mapped from userId).

scopes · string[]

The scopes requested in this authorization.

expiresIn · string

The requested grant duration.

expiresAt · string

ISO 8601 timestamp when the authorization request expires.

status · string

Current status: 'pending', 'approved', 'denied', or 'expired'.

createdAt · string

ISO 8601 timestamp when the request was created.

Full example

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

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

// Register the agent first
const agent = await grantex.agents.register({
  name: 'email-assistant',
  description: 'Reads and drafts emails on behalf of the user',
  scopes: ['email:read', 'email:send', 'contacts:read'],
});

// Start the authorization flow
const authRequest = await grantex.authorize({
  agentId: agent.id,
  userId: 'user_abc123',
  scopes: ['email:read', 'email:send'],
  audience: 'https://api.myapp.com',
  expiresIn: '7d',
  redirectUri: 'https://myapp.com/auth/callback',
});

console.log(authRequest.authRequestId); // 'areq_01HXYZ...'
console.log(authRequest.consentUrl);    // 'https://consent.grantex.dev/authorize?req=eyJ...'
console.log(authRequest.status);        // 'pending'

Next steps

After the user approves the request at the consentUrl, your redirectUri receives an authorization code. Exchange it for a grant token using tokens.exchange().