Authentication

API Key Authentication

Requests to the OpenAI-compatible API are authenticated with an API key. Send the key in one of two headers:

If a request carries both headers with a usable key, the Authorization: Bearer value is the one used. The x-api-key header is read when there is no non-empty bearer value.

Example Request

curl YOUR_BASE_URL/models \
  -H "Authorization: Bearer your-api-key"

See Authentication in the API Reference for the endpoint reference.

Obtaining an API Key

API keys are created in the AI Commons web application.

1. Sign in to AI Commons. Your account must be in the openai group, which is the access that gates the OpenAI-compatible API.
2. Go to Settings → API Keys and create a key. The page also shows the base URL to use.
3. Copy the key when it is shown. The full key value is returned only when the key is created. Later listings show key details but not the secret.
4. Store the key securely and set it in your client (see Environment Variables).

If the API Keys page reports that the feature is unavailable, see Client Configuration; group membership is the likely cause.

Keys belong to a user

Each key is tied to the user who created it, and requests made with it run as that user. Only the key's owner can revoke it. Revoke a key from the same API Keys page when it is no longer needed or may have been exposed.

Lifetime and access checks

An API key has no expiry date. Whether it keeps working depends on its owner: the owner must still be in the openai group and their account must still be enabled. A change in either takes effect on a rolling basis, up to about ten minutes after it is made. After that, requests with the key return 401.

Security Best Practices

• Never commit API keys to version control - Use environment variables or secret management systems
• Rotate keys regularly - Create a new key, switch your clients to it, then revoke the old one
• Use HTTPS only - All API requests must use HTTPS to encrypt data in transit
• Monitor usage - Track API calls to detect unauthorized access
• Use separate keys per environment - Use different keys for different environments (dev, staging, production) so any one can be revoked on its own

Authentication Errors

Errors use the OpenAI error envelope. Authentication failures return HTTP 401 with type authentication_error.

Missing key

{
  "error": {
    "message": "Missing API key. Send either `Authorization: Bearer <key>` or `x-api-key: <key>`.",
    "type": "authentication_error",
    "param": null,
    "code": null
  }
}

No usable key was found in either header. Send the key in Authorization: Bearer or x-api-key.

Invalid key

{
  "error": {
    "message": "Invalid API key.",
    "type": "authentication_error",
    "param": null,
    "code": null
  }
}

The same response is returned when the key is unknown, was revoked, or belongs to a user who is no longer in the openai group or whose account is disabled. The response does not say which. Check the key value, then check the API Keys page and your group access.

Other error types are listed under Error Handling in the API Reference.

Environment Variables

Store your API credentials as environment variables:

Bash/Zsh

export OPENAI_API_KEY="your-api-key-here"
export OPENAI_BASE_URL="your-base-url-here"

Python

import os
from openai import OpenAI
client = OpenAI(
    base_url=os.environ["OPENAI_BASE_URL"],
    api_key=os.environ["OPENAI_API_KEY"],
)
response = client.chat.completions.create(
    model="claude-v4.6-sonnet",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)

JavaScript/Node.js

import OpenAI from "openai";
const client = new OpenAI({
  baseURL: process.env.OPENAI_BASE_URL,
  apiKey: process.env.OPENAI_API_KEY,
});
const response = await client.chat.completions.create({
  model: "claude-v4.6-sonnet",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(response.choices[0].message.content);