API-Keys
Ein Key besteht aus ccsio_, gefolgt von 32 Buchstaben und Ziffern. Er gehört zu einer Organisation in einer Region und handelt mit den Berechtigungen dessen, dem er gehört:
| Art | Handelt als | Verwendung |
|---|---|---|
| Persönlicher API-Key | Du: mit deinen Rollen und Berechtigungen in der Organisation. | Deine eigenen Skripte, Notebooks und Coding-Agents. |
| Service-Account-Key | Ein Service-Account, mit der Rolle, die ein Administrator ihm gibt. | Anwendungen, Server und CI-Pipelines. |
Beide Arten erstellst du in der Console unter Identity → API keys. Der Roh-Key wird einmal angezeigt, wenn er erstellt wird; danach zeigt die Console nur noch sein Präfix.
Den Key senden
Sende den Key im Header Authorization als Bearer-Token. So machen es die OpenAI-Clients mit api_key:
curl "https://api.eu.ccsio.ai/v1/models" \
-H "Authorization: Bearer $CCSIO_API_KEY"Oder sende ihn im Header x-api-key, wenn dein Tool kein Bearer-Token setzen kann:
curl "https://api.eu.ccsio.ai/v1/models" \
-H "x-api-key: $CCSIO_API_KEY"Für ein Team handeln
Administratoren können Modelle auf einzelne Teams beschränken. Gehört der Inhaber eines Keys zu mehr als einem Team, gib das Team, für das der Aufruf handelt, in X-Team-Id an: Die Modelle, die du aufrufen darfst, die Limits und die Nutzung richten sich dann nach diesem Team. Ohne diesen Header wird ein Aufrufer mit Rollen in mehreren Teams mit 403 policy-denied abgelehnt.
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"}]}'Wenn ein Key abgelehnt wird
| Status | Fehlercode | Bedeutung |
|---|---|---|
| 401 | invalid-request | Keine Zugangsdaten oder beide Header gleichzeitig. |
| 401 | api-key-invalid | Der Wert ist kein Plattform-Key: Prüfe, ob er mit ccsio_ beginnt und vollständig ist. |
| 401 | api-key-unknown | Der Key existiert in dieser Region nicht. Keys funktionieren nur in der Region, in der sie erstellt wurden. |
| 401 | api-key-revoked, api-key-expired | Der Key wurde widerrufen oder ist abgelaufen. Erstelle einen neuen. |
| 402 | payment-required | Die Organisation hat kein aktives Abonnement. |
| 403 | policy-denied | Keine Rolle des Key-Inhabers hat die Berechtigung, oder das Team ist nicht eindeutig: Sende X-Team-Id. |
| 403 | team-not-selectable | X-Team-Id nennt ein Team, für das der Key-Inhaber nicht handeln kann. |
Jede Ablehnung hat dieselbe Form, mit einem stabilen code, nach dem du verzweigen kannst:
{
"error": {
"code": "api-key-revoked",
"category": "client",
"message": "the API key has been revoked",
"request_id": "01K7YQ4D8M2P6S9V3X5Z7B1C4F"
}
}Keys per API verwalten
Automatisierungen können Service-Accounts und deren Keys über die Management-API auf dem Host deiner Console erstellen. Der Key, der sie aufruft, braucht die Berechtigungen members.manage und api-keys.manage.
# The management APIs answer on your console's host.
export CCSIO_CONSOLE_URL="https://console.eu.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"Bewährte Praxis
- Verwende einen Key pro Anwendung und pro Umgebung, damit du einen widerrufen kannst, ohne die anderen zu stoppen.
- Gib Service-Account-Keys ein Ablaufdatum und rotiere sie, bevor es erreicht ist.
- Lies Keys aus der Umgebung oder aus einem Secret-Store, nie aus Code oder Logs.
- Widerrufe einen Key, der offengelegt worden sein könnte, sofort: Identity → API keys.