API keys
A key is ccsio_ followed by 32 letters and digits. It belongs to one organization in one region, and it acts with the permissions of whoever it belongs to:
| Kind | Acts as | Use it for |
|---|---|---|
| Personal key | You: your roles and permissions in the organization. | Your own scripts, notebooks and coding agents. |
| Service-account key | A service account, with the role an administrator gives it. | Applications, servers and CI pipelines. |
Create both kinds in the console under Identity → API keys. The raw key is shown once, when it is created; the console only shows its prefix afterwards.
Send the key
Send the key in the Authorization header as a bearer token. This is what the OpenAI clients do with api_key:
curl "https://api.us.ccsio.ai/v1/models" \
-H "Authorization: Bearer $CCSIO_API_KEY"Or send it in the x-api-key header, if your tool cannot set a bearer token:
curl "https://api.us.ccsio.ai/v1/models" \
-H "x-api-key: $CCSIO_API_KEY"Acting for a team
Administrators can restrict models to some teams. When the owner of a key belongs to more than one team, name the team the call acts for in X-Team-Id: the models you may call, the limits and the usage then follow that team. Without it, a caller with roles in several teams is refused with 403 policy-denied.
curl "$CCSIO_BASE_URL/chat/completions" \
-H "Authorization: Bearer $CCSIO_API_KEY" \
-H "X-Team-Id: devops" \
-H "Content-Type: application/json" \
-d '{"model": "qwen3.8-flash-next", "messages": [{"role": "user", "content": "Hi"}]}'When a key is refused
| Status | Code | Meaning |
|---|---|---|
| 401 | invalid-request | No credential, or both headers at once. |
| 401 | api-key-invalid | The value is not a platform key: check that it starts with ccsio_ and is complete. |
| 401 | api-key-unknown | The key does not exist in this region. Keys work only in the region they were created in. |
| 401 | api-key-revoked, api-key-expired | The key was revoked or passed its expiry. Create a new one. |
| 402 | payment-required | The organization has no active subscription. |
| 403 | policy-denied | No role of the key's owner holds the permission, or the team is ambiguous: send X-Team-Id. |
| 403 | team-not-selectable | X-Team-Id names a team the key's owner cannot act for. |
Every refusal has the same shape, with a stable code to branch on:
{
"error": {
"code": "api-key-revoked",
"category": "client",
"message": "the API key has been revoked",
"request_id": "01K7YQ4D8M2P6S9V3X5Z7B1C4F"
}
}Manage keys by API
Automation can create service accounts and their keys through the management API, on your console's host. The key that calls it needs the permissions members.manage and api-keys.manage.
# The management APIs answer on your console's host.
export CCSIO_CONSOLE_URL="https://console.us.ccsio.ai"
# 1. A service account for the application (permission members.manage).
curl "$CCSIO_CONSOLE_URL/identity/v1/service-accounts" \
-H "Authorization: Bearer $CCSIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"org_id": "acme", "display_name": "billing-app", "role": "user"}'
# → {"principal_ref": "svc/01K7YP2C9W4X5E8H3J6M0N1Q2R", "display_name": "billing-app", "kind": "service_account"}
# 2. A key for it (permission api-keys.manage). The answer carries the raw key once, in "raw": store it now.
curl "$CCSIO_CONSOLE_URL/identity/v1/api-keys" \
-H "Authorization: Bearer $CCSIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"org_id": "acme",
"name": "billing-app production",
"principal_ref": "svc/01K7YP2C9W4X5E8H3J6M0N1Q2R",
"expires_at": "2027-01-31T00:00:00Z"
}'
# 3. Revoke it when it is no longer needed, or if it leaked.
curl -X POST "$CCSIO_CONSOLE_URL/identity/v1/api-keys/01K7YQ4D8M2P6S9V3X5Z7B1C4F/revoke" \
-H "Authorization: Bearer $CCSIO_API_KEY"Good practice
- Use one key per application and per environment, so you can revoke one without stopping the others.
- Give service-account keys an expiry, and rotate them before it.
- Read keys from the environment or a secret store, never from code or logs.
- Revoke a key that may have leaked at once: Identity → API keys.