Skip to main content
CID222 Docs

Manage gateway API keys

Issue, regenerate and revoke the cid_key_ bearer tokens machine clients present to call the CID222 gateway.

  • Version: 0.4
  • Role: admin_user
  • Type: task

A gateway API key is a bearer token a machine client presents to call CID222 — an application posting to the chat endpoint, a script running detection, or a proxy validating a caller. Each key is bound to exactly one account or one tenant group and carries a rate limit plus optional monthly quotas.

What do I need?

Licence
Any
Role
admin_user

Prerequisites

  • The account or tenant group the key will speak as already exists.
  • The client that will hold the key can reach the gateway over HTTPS.
  • You have somewhere secure to put the key: it is shown once and cannot be recovered.

Note

These are not provider keys. A cid_key_ authenticates into CID222; the OpenAI or Anthropic key CID222 calls out with lives on Credentials.

Create a key

Open the page

Select Administration → API Keys.

The summary line reads {total} keys · {active} active · {revoked} revoked on this page · SHA-256 hashed at rest.

Start a new key

Select Create API key.

The Create New API Key dialog opens.

Name it and choose who it speaks as

Enter a Name, then set Assign To:

  1. Individual Tenant — the key acts as that one account. Detections, costs and policy are that account's.
  2. Tenant Group (Shared) — the key is bound to a department. Read the caveat below before choosing this.

The dialog notes Assignment cannot be changed after creation.

Set the limits

Set Rate Limit (per min), and Monthly Request Limit and Monthly Token Limit if you cap the key.

Leave a quota field empty for Unlimited; the placeholder says Leave empty for unlimited.

Create the key

Select Create.

The API Key Created dialog opens showing the key once, under the warning Important: This is the only time you will see this API key. Make sure to copy and store it securely.

Copy it before you close the dialog

Select Copy API Key, then Done.

The button flips to Copied! and a toast confirms API key copied to clipboard. After this only the key prefix is ever shown; the full key cannot be recovered and a lost key must be regenerated.

Use a key

The client sends the key as a bearer token:

curl -sS https://<appliance-fqdn>/chat/completions \
  -H "Authorization: Bearer cid_key_0123456789abcdef..." \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","provider":"openai","messages":[{"role":"user","content":"hello"}]}'

A cid_key_ reaches the endpoints that accept either a signed-in session or a key: the chat completions endpoint, the sessions behind it, the detection API, and the service-to-service key validation a fronting proxy uses. It does not reach the administrative surface — every /admin endpoint requires a signed-in account with a role, and a key has no role.

Rotate a key

Regenerate

Select Open menu → Regenerate, read the confirmation, then select Regenerate.

The confirmation warns This will generate a new API key for the named key**. The old key will be invalidated immediately. Applications using the old key will need to be updated.**

Copy the new key

The API Key Created dialog opens again with the new secret. Copy it and select Done.

The record keeps its name, owner, limits and quota counters; only the secret changes. The old secret stops working at once, so update the client in the same maintenance window.

Revoke a key

Revoke it

Select Open menu → Revoke, then Revoke in the confirmation.

The confirmation reads This will revoke the API key and Applications using this key will no longer be able to authenticate. A API key revoked successfully toast confirms it.

Confirm the row

The key stays in the list with the status Revoked.

The row is kept deliberately: its usage counters and last-used timestamp remain readable after the key is dead.

The group-key identity caveat

Warning

A key bound to a tenant group borrows a real person's identity. The gateway resolves the key to the group's earliest-added member, and everything downstream is that member's: the account named on every detection, the User column in the logs, the role check on the chat, and the filter-override pass — which resolves that borrowed member's own group memberships rather than the key's group.

Two consequences to plan around:

  • Removing that member from the group does not revoke the key. It transfers the key's identity to whoever is now earliest-added, and with it the policy the key runs under.
  • A group whose membership is empty leaves the key resolving to nobody, and the gateway refuses it rather than admitting a request with no account behind it.

Bind a key to an individual account whenever you need the attribution to be stable. A dedicated service account is the practical answer today.

Fields reference

FieldRequiredRuleWhat it does
NameYesFree textIdentifies the key in the list
Assign ToYesTenant Group (Shared) or Individual TenantWhose identity the key carries. Locked after creation
Tenant Group / TenantYesAn existing group or accountThe owner
Rate Limit (per min)NoMinimum 1Requests per minute allowed on this key
Monthly Request LimitNoMinimum 0, empty for unlimitedRequests the key may make per month
Monthly Token LimitNoMinimum 0, empty for unlimitedTokens the key may spend per month
StatusNoActive, Inactive or RevokedOnly an active key authenticates

List columns

ColumnShows
NameThe key's name
Key prefixThe first characters of the key, followed by an ellipsis
Assigned toGroup: {name} or Tenant: {name}
StatusActive, Inactive or Revoked
Requests / monthUsed against the limit, or Unlimited
Tokens / monthUsed against the limit, or Unlimited
Last usedWhen the key last authenticated, or Never

Note

The Filter keys… box and the Status filter narrow only the page in front of you. Page through the list before concluding a key is absent.

How keys are stored

A key is cid_key_ followed by 32 random bytes in hex. The appliance stores the SHA-256 hash and the first 12 characters for display — never the key itself — so a lost key cannot be recovered from the appliance, only replaced. The Last used timestamp is written at most once a minute per key, so a very recent call may not be reflected immediately.

Keys have an optional expiry in the data model (a key with none never expires), but the dashboard offers no expiry field in 0.4. Set one through the API if you need it.

Verify

  1. The new key appears in the list with the owner, limits and status you set, and Last used reads Never.
  2. Call the gateway with the key. A successful call returns a completion, and the row's Last used and quota counters advance within a minute.
  3. Call with a revoked key. The gateway answers 401 API key is not active.
  4. Key changes are not written to the audit trail in 0.4 — no RESOURCE_CREATED, RESOURCE_UPDATED or RESOURCE_DELETED row is produced. Requests made with the key are logged as normal traffic under the account the key resolves to.

If it fails

  • Invalid API key (401) — the key does not match any stored hash. It was mistyped, or it has been regenerated.
  • API key is not active (401) — the key is inactive or revoked.
  • API key has expired (401) — the key carried an expiry that has passed.
  • API key request quota exceeded / API key token quota exceeded (401) — the monthly quota is spent. Raise the limit, or wait for the counters to reset.
  • Invalid expires_at: {value} / expires_at must be in the future — a scripted call sent a malformed or past expiry.
  • API key with ID {id} not found — the key does not exist, or it belongs to a department you do not own. Regenerate refuses identically and writes nothing.
  • A create refused with 403 — the account you named is outside your scope. A group you do not own refuses with the same 404 a non-existent group gives, deliberately, so the answer does not enumerate departments.
  • Failed to create API key / Failed to regenerate API key / Failed to revoke API key — the gateway refused the write; the specific message above accompanies it.
  • Only administrators can manage API keys. — your role cannot use this page.

Next steps

  • API key testing — send a real chat request with the key you just issued and read the response.
  • Credentials — the provider keys the gateway needs before any key can do useful work.
  • Tenant groups — where a group key's borrowed identity is decided.

Last updated on

On this page

Download PDF