API Keys

An API key authenticates your requests and carries grants — the precise set of objects it may reach, and what it may do with each. A single key can invoke a model, read and write a RAG, or any combination you need.

Grants

Each grant pairs an object with an action:

Object	Actions
Model (in-cluster or external)	invoke
Model alias	invoke
RAG	read, write
Preset agent	invoke
Group	member

You can only grant access you already hold, and grants are fixed at creation — to change what a key can reach, create a new one. For a preset agent that means any agent you can use yourself, including one shared with you from the platform or another tenant. The key's page lists its grants in a table. The Resource column gives the value a client must send: for a model, the API model id — the exact string for the model field — with the object's internal name beneath it when the two differ. For a RAG endpoint or a group, the column gives the object's name. Select the name to open that object's page. The grant picker on the create form labels a model the same way, so the id you pick there is the id you send.

Alias or model

An alias is a stable public name that an administrator points at a model, and can point at another model later (see Model Gateway). You can grant a key on the alias, or on the model behind it:

• Grant on the alias — the key follows the alias. When an administrator points the alias at another model, the key keeps working and your requests go to the new model. Pick this when your code calls the alias name.
• Grant on the model — the key stays with that one model, even if the alias later points somewhere else. Pick this when you always need the same model.

An alias is offered only if you may use it yourself.

Group membership

A grant on a Group does not name one service. It makes the key a member of that group, so the key can use everything the group has access to.

What the group can reach may change later. If the group is given access to another model or RAG, the key can use that too. If the group loses that access, the key loses it as well.

Personal and service-account keys

• A personal key acts as you: it inherits a subset of your own permissions and is bound to your identity, so it stops working if you lose access. Reach for it for your own scripts and integrations. Any tenant member can create one.
• A service-account key stands on its own, independent of any user, and keeps working as people come and go. Use it for shared and production workloads. Only tenant admins can create one.

Creating a key

Create keys from the API Keys page in the portal. Every service's detail view also has a Create API key link that opens the form with the matching grant already filled in — the quickest way to scope a key to a single model or RAG.

Under Resource type, choose Model Alias to grant the key on an alias. It is already selected when there are aliases you can use. If you pick a model that an alias points at, the form tells you and offers a Use <alias> button that moves the grant to the alias. Keep your own choice to tie the key to that one model.

Resource type also offers Preset Agent. Such a grant lets the key call that agent's ID, as described under Preset agents.

Choose Group to make the key a member of a group. The list shows the groups you belong to. A tenant administrator can choose any group in the tenant. The action is Member.

The key is shown once, at creation. Copy it then; it can't be retrieved later. Only a short prefix (e.g. cm_api_3f9a…) is kept, so you can still recognize the key in the list.

Each key also has an ID. The API Keys page shows the start of it under the key's name. Open the key to see the whole ID.

Name and description

The description is a note for your team about what the key is for. It is shown only in the portal. Set it when you create the key, or later on the key's page.

Open the key from the API Keys page. The description sits at the top, under the key's name. Select the pencil next to the description to edit it, then select Save. Leave the box empty and save to remove the description.

The pencil next to the key's name opens Rename. It changes the name only.

A revoked key can no longer be renamed, and its description can no longer be changed.

Disabling and enabling

Select Disable from the key's action menu or detail page to temporarily stop all authentication with that key, including previous secrets still valid during a rotation overlap. Confirm the action to apply it. Applications using the key will lose access. Requests and streams already authorized can continue.

Disabled keys stay visible with a Disabled badge. Their grants, secrets, and expiry dates are preserved. Select Enable to allow the same unexpired secrets to work again with current permissions. Enabling does not renew expired secrets. You can rotate a disabled key to prepare a replacement secret; rotation keeps it disabled until you explicitly enable it.

Personal-key owners can disable and enable their own keys. Tenant admins can disable and enable the tenant's service-account keys. Their separate permission to revoke another user's personal key does not allow them to disable or enable it. Revoked keys cannot be enabled.

Rotating and revoking

Rotate and Revoke sit at the top right of the key's page:

• Rotate issues a fresh secret while the old one keeps working for a short overlap window — swap the new secret into your clients with no downtime, and the old one stops working once the window closes.
• Revoke asks you to confirm first, then permanently revokes the key. It cannot be enabled again.

Checking usage

Portal

Open a key from the API Keys page. The key's page has two tabs:

• Overview — the key's details: its ID, type, key prefix, when it was created, when it expires, who created it, and the key's grants. Select the copy icon next to the ID to copy the whole ID, for example to find the key in the API key usage export. Created by shows the person's name or email. A disabled key also shows Disabled on, the date it was disabled.
• Usage — how much the key has been used. It shows a Tokens over time chart, followed by Token usage totals for total, input, output, embedding, and rerank tokens.

Select Usage to see how much the key has been used. The chart opens on the last two hours. Use From and To to choose another period. While To reads Now, the chart keeps refreshing; choose a date and time there to stop at that moment. The chart and totals cover the same selected period. In the totals summary, Total tokens adds input, output, embedding, and rerank tokens. Select a token name above the chart to hide or show its line.

The tab you have open is part of the page address, so you can bookmark or share a link that opens on Usage.

You can view usage for your personal keys. Tenant administrators can also view usage for the tenant's service-account keys.

Using a key

Send the key as a bearer token to the Model Gateway:

curl -sS "https://api.<your-domain>/v1/responses" \
  -H "Authorization: Bearer cm_api_…" \
  -H "Content-Type: application/json" \
  -d '{"model": "YOUR_MODEL_ID", "input": "Hello"}'

Store keys as secrets — never in client-side code or version control.