Authentication

Send a Codius organization API key as a bearer token:

Authorization: Bearer codius_...

Keys are shown only when created. Store them in a secret manager, scope them to the least privilege required, and rotate them when exposure is suspected.

Organization ownership

API keys belong to a Codius organization, not to a model provider. Requests consume the organization’s applicable plan or explicitly enabled extra usage. Removing a member does not necessarily revoke a shared organization key, so rotate keys separately during offboarding.

Create distinct keys for local development, CI, deployed services, and third-party agent integrations. A descriptive key name makes usage and revocation easier to trace.

Scopes

Use the smallest scope set required by the client:

• models:read for model discovery;
• inference:create for chat completions;
• additional scopes only when the generated reference documents an operation that needs them.

A key without the required scope returns 403 even when the organization and subscription are otherwise valid.

Environment variables

Keep secrets outside source-controlled configuration:

export CODIUS_API_KEY="replace-with-secret-manager-value"

curl https://api.codius.ai/v1/v1/models \
  -H "Authorization: Bearer $CODIUS_API_KEY"

For CI, use the platform’s encrypted secret store and expose the value only to the job that makes the request. Avoid printing environment dumps, request headers, or full client configuration.

Failure handling

• 401 means the credential is missing, malformed, expired, or otherwise invalid.
• 403 means the authenticated key or organization is not allowed to perform the operation.
• A plan or usage problem can return a separate structured error even when authentication succeeds.

Do not retry 401 or 403 in a tight loop. Correct the credential or scope, then issue a new request.

Rotation

Create the replacement key, update consumers, confirm successful authenticated requests, then revoke the old key. Revoke immediately if a key appears in Git history, terminal output, a screenshot, a support transcript, or an exported agent session.