API keys

Overview

API keys give programmatic access to your Ken workspace. Use them to connect external tools, automation scripts, or your own MCP server without sharing your login credentials. Each key is scoped to the workspace it was created in and belongs to the user who created it.

Find API keys at Settings - Integrations - API Keys. In the left sidebar, open Settings, click the Integrations tab, then select API Keys from the secondary navigation.

Before you start

• You must be signed in to an active workspace. If no workspace is active you will see the message "Select a workspace to manage integrations."
• Every workspace role (admin, member, view-only) can create and revoke their own API keys. There is no elevated role requirement for this page.
• Each key you create is personal to your user account. Other workspace members cannot see or revoke your keys.

How to create an API key

1. Open Settings from the main sidebar.
2. Click the Integrations tab in the settings navigation.
3. Select API Keys from the secondary navigation.
4. Click Create API Key in the top-right corner of the page.
5. Enter a Name for the key (required, up to 64 characters). Use a name that identifies the integration - for example, "MCP Server" or "CI Pipeline".
6. Choose an Expiration from the dropdown. The available options are: Never, 7 days, 30 days, 60 days, or 90 days. Keys that never expire are still revocable at any time.
7. Click Create API Key.
8. A confirmation step shows the key secret. Copy the secret immediately - this is the only time it will be shown. Click the Copy button to copy it to your clipboard.
9. Click Done to close the dialog.

The new key appears in the table with columns: Name, Created on, and Expires.

Store the secret safely

After you close the creation dialog, the secret is gone from the UI permanently. Ken stores only a hashed reference to the key, not the plaintext value. If you lose the secret, revoke the key and create a new one.

Keep your secret out of source control. Set it as an environment variable or store it in a secrets manager.

How to revoke an API key

Revoking a key is immediate and permanent. Any integration using that key will stop working straight away.

1. Go to Settings - Integrations - API Keys.
2. Find the key you want to remove in the table.
3. Click the trash icon on the right side of that row.
4. In the confirmation dialog, click Yes, revoke it.

The key disappears from the table. Revoked keys are not shown.

How it works

One key per user, scoped to one workspace. When you create a key, the backend generates a secret and ties it to your user identity within the active workspace. The key carries an admin:write scope, which covers all standard API operations. There is no read-only key tier.

Authentication flow. Send the key as a bearer token in the Authorization header of each request:

Authorization: Bearer <your-secret>

The request passes through a gateway that identifies the rate-limit bucket, then hits the API middleware. The middleware detects that the token is an opaque bearer (not a JWT), validates it against the key store, checks the workspace membership, and builds an identity for the request. If the key is valid and not revoked, the request proceeds with your workspace context attached.

Expiration. If you chose an expiry when creating the key, requests made after that date return 401. A key expiring in 7 days is valid for exactly 7 days from creation. Non-expiring keys remain valid until you revoke them.

Validation caching. Keys are validated and cached after the first successful request. Revocation invalidates the cache immediately - a revoked key will not pass a cached check. If the underlying auth service is temporarily unavailable, the API returns 503 with a Retry-After header rather than failing open.

Rate limits. Standard API keys are subject to rate limits applied per key: 60 requests per minute and 1,000 requests per day. When a limit is hit, the response is 429 with X-RateLimit-* headers indicating the window and retry time. A second rate-limit layer at the gateway applies independently to public v2 API routes.

Developer reference. A public API reference is available at developer.getken.ai. It documents the v2 API surface and requires no authentication to browse.

Troubleshooting & debugging

401 on every request

• Likely cause: the key was revoked, or the secret was copied incorrectly.
• Check: go to Settings - Integrations - API Keys and confirm the key is still listed. Revoked keys do not appear. If it is missing, the key was revoked.
• Fix: create a new key and update your integration with the new secret.

401 on every request after the key still appears in the UI

• Likely cause: the secret was not copied correctly at creation time (common if the dialog was closed before clicking Copy).
• Fix: revoke the key, create a replacement, and copy the new secret before closing the dialog.

401 with a key that recently expired

• Likely cause: the key was created with a fixed expiration (7, 30, 60, or 90 days) and has now passed that date.
• Check: look at the Expires column in the API keys table. If it shows a past date, the key is expired.
• Fix: create a new key with a longer or no expiration.

503 with Retry-After header

• Likely cause: the auth service that validates keys is temporarily unavailable. This is a transient platform condition.
• Fix: wait the number of seconds indicated by Retry-After and retry. Do not regenerate the key.

429 Too Many Requests

• Likely cause: your integration is exceeding 60 requests per minute or 1,000 requests per day for this key.
• Check: inspect the X-RateLimit-Remaining and X-RateLimit-Reset response headers to see the current window state.
• Fix: add back-off and retry logic in your integration. If your legitimate usage exceeds these limits, contact support.

Page shows "Integrations unavailable - Your role is not allowed to manage API keys for this workspace."

• Likely cause: the backend returned a 403, which can happen if the role context is inconsistent.
• Fix: sign out and sign back in. If the message persists, confirm you are a member of the workspace you are trying to access.

Page shows "Select a workspace to manage integrations."

• Likely cause: no active workspace is selected in the session.
• Fix: switch to an active workspace from the workspace selector and reload the page.

Key does not appear in the table after creation

• Likely cause: the key was created successfully but the table still shows a cached result from before.
• Fix: refresh the page. The table fetches fresh data on load.

FAQ

Can I create multiple keys? Yes. There is no hard limit shown in the UI. Create separate keys for each integration so you can revoke one without affecting others.

Can a teammate see or revoke my keys? No. Keys are personal to the user who created them. Other workspace members, including admins, cannot see or manage your keys through this interface.

What scope does a key have? All keys carry the admin:write scope, which covers the full API surface available to authenticated workspace members. There is no read-only key option.

What happens when I revoke a key? Revocation is immediate. The key is removed from the table and any in-flight or future request using that secret receives a 401. There is no grace period.

Can I rename or edit a key after creating it? No. Keys cannot be edited after creation. If you need a different name, revoke the existing key and create a new one.

Is there a public API reference I can link my developers to? Yes. The v2 API reference is publicly available at developer.getken.ai. No login is required.

Related articles

• Webhooks