Getting started

Authentication

We use two key authentication methods to identify you and your player. This layered authentication approach allows you to track usage statistics, manage costs, and remove access from abusive players if necessary — something you can't do with just a single API key.

Project Identification

API Key

All requests to the API must include an API key as a Bearer token in the Authorization HTTP header. This key is used to identify your project, authenticate you as a developer, and track resource usage for billing. You can create as many API keys as you need for different projects or environments (development, staging, production).

Each API key has its own settings for text and image generation, including default model parameters. These settings serve as project-wide defaults but can be overridden in individual requests.

Include your API key in all requests as an HTTP header:
Authorization: Bearer cg-abcd1234

Security Tips:

Store API keys securely in environment variables or a secure key management system
Never expose API keys in client-side code or public repositories
Rotate keys periodically for enhanced security

Player Identification

Client ID

Most requests to the API also require a client_id parameter in the request body. This ID is used to identify individual players or end-users making requests through your application. The client_id can be any string value that makes sense for your application.

Common client_id examples include:

User IDs from your database (e.g., user_12345)
Session IDs (e.g., session_9b72eb)
Anonymized UUIDs for privacy (e.g., anon_73e8ff3d)

Client IDs enable you to:

Track usage statistics per player
Identify power users or abusive patterns
Selectively restrict access if needed
Analyze feature adoption and retention metrics

You can view detailed statistics for each client_id on your API key's "Usage" page.

Include the client_id in the JSON body of your request:
"client_id": "player_12345"

Complete Authentication Example

Complete Request Example

curl -X POST https://api.chromagolem.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cg-abcd1234efgh5678" \
  -d '{
    "client_id": "player_12345",
    "model": "gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful game assistant."
      },
      {
        "role": "user",
        "content": "What should I do next in my adventure?"
      }
    ]
  }'

Authentication Flow

API Key: Added as a Bearer token in the HTTP Authorization header
Client ID: Included in the request body as a JSON parameter
Both are validated by our API before processing your request
Usage metrics are tracked for both your API key (billing) and client_id (analytics)

Common Issues

401 Unauthorized	API key is invalid, expired, or missing
400 Bad Request	Missing required client_id in request body
403 Forbidden	API key doesn't have permission for the requested resource