API keys

The API keys screen lets you create scoped tenant keys for an application or a pipeline, rotate them and revoke them; the secret is shown once, at creation or rotation. Portal path: /admin/api-keys. It is used by the tenant administrators (tenant_admin), the developers (developer, for their own keys) and the security officers (security_officer, for incident response).

What the screen shows

An API keys table with Refresh and New API key:

Column	Content
Name	Name of the key.
Prefix	First characters of the key, to recognize it in logs.
Scopes	Scopes granted, for example models:invoke, agents:run.
Roles	Roles carried by the key.
Revoked	Yes once the key is revoked.
Last used	Date of the last use.
Expires	Expiry date, empty for a key without expiry.
Created	Creation date.

The list is paged. A developer sees only the keys they created; tenant_admin, security_officer and platform_admin see every key of the tenant. Empty state: No API key, "Create a scoped key for an application or a pipeline."

After a creation or a rotation, the dialog Secret created shows the key with a copy button and the warning "Copy it now: it is shown only once and cannot be retrieved later."

Actions

Button or action	What it does	API call	Roles
Opening the screen, Refresh	Reads the keys page by page.	GET /v1/api-keys	tenant_admin, security_officer, developer
New API key then Create	Form Name (required), Scopes (required list; suggestions models:invoke, agents:run, tools:invoke, rag:query, finops:read, admin:*), Expires (date and time, for example 2027-01-01T00:00:00Z). The secret is shown once.	POST /v1/api-keys	tenant_admin, developer
Rotate	Browser confirmation "Rotate <name>? This action is recorded in the audit log.", then a replacement key with the same name, scopes and roles; the new secret is shown once. The portal sends no grace period.	POST /v1/api-keys/{id}/rotate	tenant_admin, security_officer, developer (own keys)
Revoke	Destructive confirmation, then the key stops working.	DELETE /v1/api-keys/{id} (impact: GET /v1/lineage/graph)	tenant_admin, security_officer, developer (own keys)

Roles

From services/control-plane/src/eai/domains/identity/__init__.py:

• Listing, rotating and revoking require tenant_admin, security_officer or developer; creating requires tenant_admin or developer (platform_admin always passes).
• A developer only manages the keys they created: another key answers not_found.
• A key never receives a scope the caller does not hold (scope_not_held), nor a role above the caller's; the platform_admin role is reserved to a platform_admin.
• A security_officer without an administrator role rotates any key except a key carrying tenant_admin.

danger

The secret is shown only once. Store it at once in the secret manager of the application; if it is lost, rotate the key. Revoke a key at once when it leaks.

Typical tasks

Create a key for a pipeline

1. Open the form. Button New API key. Expected result: the side form. If it fails: forbidden at submit time when you are neither tenant_admin nor developer.
2. Give the smallest scopes. Name: ci-pipeline; Scopes: only what the pipeline calls, for example agents:run; Expires: a date. Then Create. Expected result: the dialog Secret created. If it fails: forbidden with scope_not_held when you ask for a scope you do not hold yourself.
3. Copy the secret. Copy button of the dialog, then paste it in the secret store of the pipeline. Expected result: the pipeline authenticates. If it fails: the dialog was closed before the copy; rotate the key to get a new secret.

Rotate a key

1. Open the action. Row menu > Rotate, accept the browser confirmation. Expected result: the dialog Secret created with the new secret. If it fails: not_found for a key of another developer.
2. Replace the secret where it is used. Expected result: the client works with the new key; Last used of the new line moves. If it fails: the client still sends the old key; update its configuration.

Revoke a leaked key

1. Revoke. Row menu > Revoke, confirm. Expected result: Revoked shows yes. If it fails: forbidden when your role cannot manage keys.

Troubleshooting

Symptom	Cause	Fix
forbidden (HTTP 403) with scope_not_held	A requested scope is not held by your own identity.	Ask only scopes you hold, or ask a tenant_admin.
forbidden (HTTP 403) with required_roles	Your role cannot list, create or rotate keys, or the key carries a role above yours.	Ask a tenant_admin.
not_found (HTTP 404) on Rotate or Revoke	The key belongs to another developer, or it no longer exists.	Ask its owner or a tenant_admin.
tenant_required (HTTP 403)	The session does not act inside a tenant.	Sign in with an account of the tenant.
The secret is lost	The dialog Secret created was closed.	Rotate the key.
Validation error on Expires	The value is not a date and time.	Use the format 2027-01-01T00:00:00Z.

Related pages

• Service identities
• Members and roles
• API reference
• Security documentation