Authentication

API Key Authentication

API keys are the simplest way to authenticate with the Creor API. They are intended for server-side integrations, scripts, and CI/CD pipelines where you can securely store a secret.

Obtaining an API Key

• Sign in to the Creor dashboard at dashboard.creor.ai.
• Navigate to Settings > API Keys.
• Click "Create New Key" and give it a descriptive name.
• Copy the key immediately -- it is only shown once.

Basic Auth

Pass your API key as the username in HTTP Basic Authentication. Leave the password field empty. The API server expects the key followed by a colon, base64-encoded in the Authorization header.

curl https://api.creor.ai/v1/chat/completions \
  -u YOUR_API_KEY:

This is equivalent to setting the header directly:

curl https://api.creor.ai/v1/chat/completions \
  -H "Authorization: Basic $(echo -n 'YOUR_API_KEY:' | base64)"

Bearer Token (Alternative)

You can also pass the API key as a Bearer token. This is useful when working with SDKs that expect a Bearer token format.

curl https://api.creor.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY"

Device Code Flow

The device code flow is designed for IDE integrations where users authenticate through a browser. Creor's desktop editor uses this flow to sign users in without requiring them to paste an API key.

How It Works

• The IDE requests a device code from the Creor auth server.
• The user is shown a URL and a short code to enter in their browser.
• The IDE polls the auth server until the user completes the browser flow.
• Once approved, the IDE receives an access token and a refresh token.
• The access token is used for API requests; the refresh token renews it when it expires.

Step 1: Request a Device Code

POST https://auth.creor.ai/device/code
Content-Type: application/json

{
  "client_id": "creor-ide",
  "scope": "api offline_access"
}

The response includes a verification URL, a user code, and a device code for polling:

{
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://creor.ai/activate",
  "expires_in": 900,
  "interval": 5
}

Step 2: Direct the User to Verify

Display the verification_uri and user_code to the user. They will open the URL in their browser, sign in (or use an existing session), and enter the code to authorize the device.

Step 3: Poll for the Token

POST https://auth.creor.ai/oauth/token
Content-Type: application/json

{
  "client_id": "creor-ide",
  "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS"
}

Poll at the interval specified in the initial response (typically 5 seconds). The server returns authorization_pending until the user completes the flow, then returns the tokens:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "v1.MR5wOHNlcnZlcl...",
  "token_type": "Bearer",
  "expires_in": 3600
}

JWT Tokens

The Creor web dashboard authenticates using JWT tokens issued after OAuth sign-in with GitHub or Google. These tokens are short-lived and automatically refreshed by the dashboard client.

Token Structure

Creor JWTs are signed with HS256 and contain the following claims:

Using JWT Tokens

Pass the JWT as a Bearer token in the Authorization header. This is the same format used for API keys, so the server distinguishes them by token format.

curl https://api.creor.ai/v1/chat/completions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Refreshing Tokens

When the access token expires, use the refresh token to obtain a new one without requiring the user to sign in again:

POST https://auth.creor.ai/oauth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "v1.MR5wOHNlcnZlcl..."
}

Code Examples

curl

# Basic Auth with API key
curl https://api.creor.ai/v1/chat/completions \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "messages": [
      {"role": "user", "content": "Explain async/await in JavaScript"}
    ]
  }'

JavaScript / TypeScript

Python

Security Best Practices

• Store API keys in environment variables or a secrets manager, never in source code.
• Use the least-privileged key scope for each integration.
• Rotate API keys periodically and immediately if you suspect a leak.
• Set IP allowlists on API keys when your integration runs from a fixed set of IPs.
• Use the device code flow for desktop applications instead of asking users to paste API keys.
• Monitor the API Keys page in the dashboard for unexpected usage patterns.
• Revoke unused keys promptly. Each key shows its last-used timestamp in the dashboard.