Skip to main content
CID222Documentation

Authentication

CID222 authenticates API requests with either a tenant API key or a short-lived user JWT. This guide covers how to obtain and use each.

Authentication Flow

CID222 supports two authentication methods:

  1. API Keys — Long-lived tenant tokens (prefixed cid_key_) for server-to-server communication
  2. JWT Tokens — Short-lived tokens obtained via login for user-based access

Using API Keys

API keys are the simplest way to authenticate. They are prefixed with cid_key_ — include yours in the Authorization header:

API Key Authentication
curl -N -X POST https://api.cid222.ai/chat/completions \
  -H "Authorization: Bearer cid_key_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [...]}'

Security Best Practices

  • Never expose API keys in client-side code
  • Rotate keys regularly
  • Use separate keys for development and production
  • Set appropriate rate limits per key

JWT Authentication

For user-based access, obtain a JWT token by authenticating with credentials:

Obtain JWT Token
const response = await fetch('https://api.cid222.ai/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    username: 'your-username',
    password: 'your-password'
  })
});


// Returns { access_token, tenant_id, username, contact_email, role }
const { access_token } = await response.json();


// Use the token in subsequent requests
const chatResponse = await fetch('https://api.cid222.ai/chat/completions', {
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  // ...
});

Token Structure

JWT tokens contain the following claims:

JWT Payload
{
  "sub": "tenant-uuid",
  "username": "user@example.com",
  "role": "admin_user",
  "iat": 1699900000,
  "exp": 1699986400
}
ClaimDescription
subTenant/User ID
usernameAccount username
roleUser role (admin_user, user)
expToken expiration timestamp

Token Expiration

JWT tokens expire after 24 hours. Handle expiration gracefully in your application:

Handle Token Refresh
async function makeAuthenticatedRequest(url, options) {
  let response = await fetch(url, {
    ...options,
    headers: {
      ...options.headers,
      'Authorization': `Bearer ${getStoredToken()}`
    }
  });


  // If token expired, refresh and retry
  if (response.status === 401) {
    const newToken = await refreshToken();
    response = await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${newToken}`
      }
    });
  }


  return response;
}

Role-Based Access Control

CID222 supports two user roles with different permissions:

RolePermissions
admin_userFull access including tenant management, credentials, filters, and user administration
userChat completions, session management, view-only access to configurations

Error Responses

401 Unauthorized
{
  "statusCode": 401,
  "message": "Invalid or expired token",
  "error": "Unauthorized"
}
403 Forbidden
{
  "statusCode": 403,
  "message": "Insufficient permissions for this operation",
  "error": "Forbidden"
}

Next Steps