Skip to main content

​
Overview

PKCE (Proof Key for Code Exchange) prevents authorization code interception attacks. Grantex supports the S256 challenge method as defined in RFC 7636. The SDK provides a generatePkce() helper that generates a cryptographically secure code verifier and its corresponding S256 challenge.

​
Import

import { generatePkce } from '@grantex/sdk';
This function does not require a Grantex client instance. It uses Node.js crypto under the hood.

​
generatePkce()

const pkce = generatePkce();

console.log(pkce.codeVerifier);         // Random 43-character base64url string
console.log(pkce.codeChallenge);        // SHA-256 hash of the verifier, base64url-encoded
console.log(pkce.codeChallengeMethod);  // 'S256'

​
Response: PkceChallenge

​
codeVerifier
string
A 32-byte random value encoded as base64url. Keep this secret — it is used in the token exchange step.
​
codeChallenge
string
The SHA-256 hash of codeVerifier, encoded as base64url. This is sent in the authorize request.
​
codeChallengeMethod
'S256'
Always 'S256'.

​
Full PKCE flow

​
Step 1: Generate the PKCE pair

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

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

// Store codeVerifier securely (e.g. in a session)
session.codeVerifier = pkce.codeVerifier;

​
Step 2: Authorize with the code challenge

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',
  codeChallenge: pkce.codeChallenge,
  codeChallengeMethod: pkce.codeChallengeMethod,
});

// Redirect the user to authRequest.consentUrl

​
Step 3: Exchange with the code verifier

// In your /auth/callback handler:
const token = await grantex.tokens.exchange({
  code: req.query.code,
  agentId: agent.id,
  codeVerifier: session.codeVerifier,  // proves possession of the original challenge
});

console.log(token.grantToken);
If a codeChallenge was provided in the authorize step, the codeVerifier is required in the exchange step. The server will reject the request if the verifier does not match the original challenge.

​
Security considerations

  • The codeVerifier must be stored server-side (e.g. in a session or encrypted cookie). Never expose it to the client.
  • Each PKCE pair is single-use. Generate a new pair for every authorization flow.
  • The S256 method is mandatory — plain challenge methods are not supported.