Authorization

All API requests require authentication using JWT tokens. You’ll generate these tokens using a private key obtained from your portal, then include them in the Authorization header as a Bearer token.

Overview

The authorization flow involves:

1. Generating a private key from the portal
2. Creating a JWT token with your external ID and role
3. Including the JWT as a Bearer token in API requests

Authentication Header

Include your JWT token in all API requests:

Authorization: Bearer YOUR_JWT_TOKEN

JWT Generation

Generate JWT for Server Side

For server side applications, you’ll generate a private application JWT.

import { jwt } from '@basistheory/ai-sdk';
 
const jwt = jwt.generatePrivate(privateKey, externalId, expiration = '1m');

Generate JWT for Client Side

For client side applications, you’ll generate a private application JWT.

import { jwt } from '@basistheory/ai-sdk';
 
const jwt = jwt.generatePublic(privateKey, externalId, expiration = '1m');

Required Claims

Security Best Practices

1. Keep your secret key secure - Never expose it in client-side code
2. Use appropriate expiration times - Shorter for sensitive operations
3. Validate tokens on every request - Always verify token integrity
4. Handle expired tokens gracefully - Implement proper error handling, acquire a new one.