Skip to main content
CID222
CID222Documentation

Authentication

CID222 uses JWT (JSON Web Tokens) for secure API authentication. This guide covers how to obtain and use tokens for API access.

Authentication Flow

CID222 supports two authentication methods:

  1. API Keys — Long-lived tokens 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. Include your key in the Authorization header:

API Key Authentication
curl -X POST https://api.cid222.ai/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "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'
  })
});


const { access_token, expires_in } = 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, normal_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
normal_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