Cuadra AI - Connect, Train, and Deploy Your Custom AI Assistant

Which Method Should I Use?

Scenario	Method	Why
React/Next.js app	JWT Sessions	User is logged in, token comes from auth flow
Mobile app	JWT Sessions	Same as web—user session based
Backend service	M2M OAuth 2.0	No user session, server-to-server calls
CLI tool	M2M OAuth 2.0	Automated scripts, no browser
Cron job	M2M OAuth 2.0	Background tasks, no user context

JWT Session Tokens

For frontend apps where users authenticate via Stytch B2B (magic link, SSO, or password).

Usage

curl -X POST https://api.cuadra.ai/v1/chats \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "model_123",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

import httpx

session_token = get_session_token()  # From your auth system

response = httpx.post(
    "https://api.cuadra.ai/v1/chats",
    headers={"Authorization": f"Bearer {session_token}"},
    json={
        "modelId": "model_123",
        "messages": [{"role": "user", "content": "Hello"}]
    }
)
print(response.json())

const sessionToken = await getSessionToken(); // From your auth system

const response = await fetch('https://api.cuadra.ai/v1/chats', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sessionToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    modelId: 'model_123',
    messages: [{ role: 'user', content: 'Hello' }]
  })
});
const data = await response.json();

With React UI Kit

import { CuadraChat } from '@cuadra-ai/uikit';

function App() {
  const sessionToken = useSessionToken();

  return (
    <CuadraChat
      connection={{ baseUrl: "https://api.cuadra.ai", sessionToken }}
      chat={{ modelId: "model_123" }}
    />
  );
}

M2M OAuth 2.0

For backend services using OAuth 2.0 Client Credentials flow.

Step 1: Get Credentials

Create M2M client credentials in Dashboard → Settings → API Access. Assign scopes based on what the service needs.

Step 2: Exchange for Token

Exchange your client credentials for an access token: Token Endpoint:

https://auth.cuadra.ai/v1/oauth2/token

curl -X POST "https://auth.cuadra.ai/v1/oauth2/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "m2m-client-xxx",
    "client_secret": "secret-xxx",
    "grant_type": "client_credentials"
  }'

import httpx

response = httpx.post(
    "https://auth.cuadra.ai/v1/oauth2/token",
    json={
        "client_id": "m2m-client-xxx",
        "client_secret": "secret-xxx",
        "grant_type": "client_credentials"
    }
)
token_data = response.json()
access_token = token_data["access_token"]  # Valid for 1 hour

const response = await fetch('https://auth.cuadra.ai/v1/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_id: 'm2m-client-xxx',
    client_secret: 'secret-xxx',
    grant_type: 'client_credentials'
  })
});
const { access_token } = await response.json(); // Valid for 1 hour

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600
}

Step 3: Use the Token

curl -X POST https://api.cuadra.ai/v1/chats \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"modelId": "model_123", "messages": [{"role": "user", "content": "Hello"}]}'

import httpx

response = httpx.post(
    "https://api.cuadra.ai/v1/chats",
    headers={"Authorization": f"Bearer {access_token}"},
    json={"modelId": "model_123", "messages": [{"role": "user", "content": "Hello"}]}
)
print(response.json())

const response = await fetch('https://api.cuadra.ai/v1/chats', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    modelId: 'model_123',
    messages: [{ role: 'user', content: 'Hello' }]
  })
});
const data = await response.json();

Token Caching

M2M tokens expire after 1 hour. Cache and refresh before expiry:

from datetime import datetime, timedelta
import httpx

class TokenManager:
    TOKEN_URL = "https://auth.cuadra.ai/v1/oauth2/token"
    
    def __init__(self, client_id, client_secret):
        self.client_id = client_id
        self.client_secret = client_secret
        self._token = None
        self._expires_at = None

    async def get_token(self):
        if self._token and self._expires_at > datetime.utcnow():
            return self._token
        
        async with httpx.AsyncClient() as client:
            response = await client.post(
                self.TOKEN_URL,
                json={
                    "client_id": self.client_id,
                    "client_secret": self.client_secret,
                    "grant_type": "client_credentials"
                }
            )
            data = response.json()
            self._token = data["access_token"]
            # Refresh 5 minutes before expiry
            self._expires_at = datetime.utcnow() + timedelta(seconds=data["expires_in"] - 300)
            return self._token

class TokenManager {
  static TOKEN_URL = 'https://auth.cuadra.ai/v1/oauth2/token';
  
  constructor(clientId, clientSecret) {
    this.clientId = clientId;
    this.clientSecret = clientSecret;
    this.token = null;
    this.expiresAt = null;
  }

  async getToken() {
    if (this.token && this.expiresAt > Date.now()) {
      return this.token;
    }

    const response = await fetch(TokenManager.TOKEN_URL, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        client_id: this.clientId,
        client_secret: this.clientSecret,
        grant_type: 'client_credentials'
      })
    });

    const data = await response.json();
    this.token = data.access_token;
    // Refresh 5 minutes before expiry
    this.expiresAt = Date.now() + (data.expires_in - 300) * 1000;
    return this.token;
  }
}

Scopes

Scope	Permission
`chat:invoke`	Create chat completions (billable)
`chat:read`	Read chat history
`chat:write`	Create, update, delete chats
`models:read`	List and view models
`models:write`	Create, update, delete models
`datasets:read`	View datasets
`datasets:write`	Create, update, delete datasets
`files:read`	View and download files
`files:write`	Upload, update, delete files
`particles:read`	View particles
`particles:write`	Create, update, delete particles
`system-prompts:read`	View system prompts
`system-prompts:write`	Create, update, delete system prompts
`usage:read`	View usage and credit balance
`org:admin`	Organization admin access

Request minimum necessary scopes for each service.

Security Best Practices

Never expose tokens in client-side code — Use a backend proxy for production
Store secrets in environment variables — Not in code or version control
Rotate M2M credentials every 90 days — Dashboard → Settings → API Access
Use HTTPS only — The API rejects HTTP requests
Scope credentials minimally — Only request permissions you need

Troubleshooting

Error	Cause	Solution
`401 Unauthorized`	Invalid or expired token	Refresh M2M token; verify JWT session
`403 Forbidden`	Missing scope	Request credentials with required scopes
`Token Expired`	M2M token past 1 hour	Request new token

FAQ

Can I use API keys instead of OAuth?

No. Cuadra AI uses OAuth 2.0 for server-side authentication. M2M credentials function similarly to API keys but require a token exchange step for security.

How do I revoke a compromised token?

For M2M: Rotate the client secret in Dashboard → Settings → API Access. For JWT: Revoke the user session in your Stytch dashboard.

What’s the token lifetime?

M2M access tokens expire after 1 hour. JWT session tokens follow your Stytch session configuration (typically 24 hours to 30 days).

Do I need separate credentials for staging vs production?

Recommended. Create separate M2M clients per environment to isolate access and simplify rotation.

API Overview

Base URL, rate limits

Errors

Error handling

Getting Started

API Reference

Guides

Billing

Authentication

Which Method Should I Use?

JWT Session Tokens

Usage

With React UI Kit

M2M OAuth 2.0

Step 1: Get Credentials

Step 2: Exchange for Token

Step 3: Use the Token

Token Caching

Scopes

Security Best Practices

Troubleshooting

FAQ

Can I use API keys instead of OAuth?

How do I revoke a compromised token?

What’s the token lifetime?

Do I need separate credentials for staging vs production?

API Overview

Errors

​Which Method Should I Use?

​JWT Session Tokens

​Usage

​With React UI Kit

​M2M OAuth 2.0

​Step 1: Get Credentials

​Step 2: Exchange for Token

​Step 3: Use the Token

​Token Caching

​Scopes

​Security Best Practices

​Troubleshooting

​FAQ

​Can I use API keys instead of OAuth?

​How do I revoke a compromised token?

​What’s the token lifetime?

​Do I need separate credentials for staging vs production?

​Related

API Overview

Errors

Which Method Should I Use?

JWT Session Tokens

Usage

With React UI Kit

M2M OAuth 2.0

Step 1: Get Credentials

Step 2: Exchange for Token

Step 3: Use the Token

Token Caching

Scopes

Security Best Practices

Troubleshooting

FAQ

Can I use API keys instead of OAuth?

How do I revoke a compromised token?

What’s the token lifetime?

Do I need separate credentials for staging vs production?

Related