Authentication

Intentgine uses a two-step authentication flow: exchange your API Key for a short-lived JWT, then use the JWT for all subsequent requests.

API Keys

You can view and manage your API keys in the Developer Console.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication Flow

Step 1: Exchange API Key for JWT

Send your API key as a Bearer token to the /v1/auth endpoint:

POST /v1/auth
Authorization: Bearer sk_live_...

The response contains a short-lived JWT (expires after 1 hour):

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2025-01-15T13:00:00.000Z",
  "app_id": "your-app-id"
}

Step 2: Use the JWT

Use the returned JWT as the Bearer token for all other API requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

When the JWT expires, exchange your API key again to get a new one.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Server-to-server only

Intentgine is a server-to-server API and does not return CORS headers. Browser-based requests (e.g. from a frontend app) will be blocked by the browser’s same-origin policy. Call the API from your backend instead.

Examples

Exchanging the API Key

cURL

curl -X POST https://api.intentgine.dev/v1/auth \
  -H "Authorization: Bearer sk_live_1234567890abcdef"

TypeScript

const auth = await fetch('https://api.intentgine.dev/v1/auth', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sk_live_1234567890abcdef' }
});
const { token } = await auth.json();

Python

import requests
auth = requests.post('https://api.intentgine.dev/v1/auth',
  headers={"Authorization": "Bearer sk_live_1234567890abcdef"})
token = auth.json()["token"]

Making Authenticated Requests

cURL

curl https://api.intentgine.dev/v1/banks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

TypeScript

const response = await fetch('https://api.intentgine.dev/v1/banks', {
  headers: { 'Authorization': `Bearer ${token}` }
});

Python

response = requests.get('https://api.intentgine.dev/v1/banks',
  headers={"Authorization": f"Bearer {token}"})

Errors

Code	Description
401	Unauthorized. The API key or JWT is missing or invalid.
403	Forbidden. The token is valid, but the App does not have permission for this action.
429	Too Many Requests. Auth exchange is rate limited to 60 requests per minute per API key.