Skip to main content

​
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'],
  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.
​
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'],
  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().