API Keys api_keys
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through api_keys_read and changes through api_keys_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.
Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.
Operations: api-keys-create, delete, api-keys-list, webhook-event-types-list, webhook-endpoints-recover, api-keys-update
api-keys-create
Write. POST https://api.ken.so/v1/api-keys
Body (json): apiVersion string, expiresInDays integer, name string, templateId integer
Create an API key held to a permission template. The secret is returned once. name and template_id are required. expires_in_days is 1..90, default 30. api_version pins the key (a date, 1.1, legacy or 1.0); omitted, the newest version.
POST /api/v1/api-keys with Ken-Version 1.1 and X-Ken-Workspace-Id.
Internal exposure. HTTP 201. Envelope: success plus data.
name is required, 1..100 characters. template_id is required: a
permission template of this workspace (permissions(operation="list")).
The key gets your permissions intersected with the template, never more
than you have, and works only in this workspace. A template of another
workspace is 404, and so is any template while permission management is
off for the workspace. expires_in_days is 1..90; omitted, the key expires
in 30 days. A key with your full permissions, or one that never expires,
is made by the user in the dashboard, not here.
api_version (DEV-15) pins the key to a dated API version: a request with
the key and no Ken-Version header gets that version's shapes. Omitted, the
backend pins the newest version. Pass "legacy" (or "1.0", the same) for a
key that replaces one used by a script calling the API without a
Ken-Version header, or it gets the new response shapes on the shared paths. "1.1" is the first dated
version. Supported values are in contracts/api-versions.json, less any version
whose retiresOn has come (UTC) and its aliases; another value is a validation
error here. data.apiVersion in the response is the stored
pin ("legacy" or a date). Change it later with
api_keys(operation="api-keys-update").
data.secret is shown once and is not returned by later list calls. Store
it immediately. data.prefix is the first 13 characters of the secret;
list calls return it to identify the key.
A session signed in with a Kenso API key cannot create keys (403
forbidden); only a session signed in with OAuth can.
A person holds at most 20 active (not revoked, not expired) keys. Past
that the create is 409 invalid_state with error.details[0].code
api_key_limit_reached: revoke one with api_keys(operation="delete")
first, never one named "Ken team" or "Ken in Slack" (revoking those
breaks an agent team or Slack). Retrying does not help.
delete
Write. DELETE https://api.ken.so/v1/api-keys/{apiKeyId}
Path: apiKeyId
Revoke one of the caller's API keys. Empty success means the key was revoked.
DELETE /api/v1/api-keys/{apiKeyId} with Ken-Version 1.1 and
X-Ken-Workspace-Id. Internal exposure. The backend returns 204 with
an empty body. api_key_id is the key id string, not the secret.
A session signed in with a Kenso API key can revoke only that key (403
forbidden for any other).
api-keys-list
Read. GET https://api.ken.so/v1/api-keys
Query: cursor string, limit integer
List the caller's API keys, including revoked keys. Secrets are omitted. client_id selects the workspace header.
GET /api/v1/api-keys with Ken-Version 1.1 and X-Ken-Workspace-Id. Internal exposure. Secrets are omitted. Revoked keys are included. limit is 1..200; omit it for the backend default of 50. cursor is pagination.nextCursor. Envelope: success, data array, pagination. Each key has id, name, prefix, createdAt, updatedAt, expiresAt, lastUsedAt, isRevoked, apiVersion and, when it is held to one, permissionTemplate. apiVersion is the API version the key is pinned to: a date, or "legacy" for a key with no pin. prefix is the first 13 characters of the secret (ken_ plus 9), so a user can tell keys apart; it is missing for keys created before prefixes were stored. lastUsedAt is when the key last authenticated a request, accurate to about 5 minutes; it is missing until the key is used. A missing field means null.
webhook-event-types-list
Read. GET https://api.ken.so/v1/webhook-event-types
List the webhook event types this workspace can subscribe to. Public. Each type has its group, description, filters, whether it is an MCP event, and a sample body.
GET /api/v1/webhook-event-types. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Same permission as webhooks(operation="list"). One page, in display order. Each item: name (what events and event_type take), group and groupLabel (the Settings section), description, mcp (offered as an MCP event), filters (campaign, classification, channel: the delivery filters the type supports), highVolume (fires often enough to be worth batching) and sample (an example body with made-up values, shaped like a real delivery). Types still rolling out are listed only for workspaces they are on for.
webhook-endpoints-recover
Write. POST https://api.ken.so/v1/webhook-endpoints/{webhookEndpointId}/recover
Path: webhookEndpointId
Body (json): since date-time, until date-time
Resend every failed delivery to one webhook endpoint since a time. Public. Requires full access. since is at most 14 days ago; until defaults to now.
POST /api/v1/webhook-endpoints/{webhookEndpointId}/recover. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. since and until are ISO 8601 UTC date-times. Resends each delivery in the
window that failed and never succeeded; Svix runs the resends in the background, so the result is
202 with data.since and data.until. Use it after an outage on the receiving side; one delivery is
webhooks(operation="resend"). Counts as 10 resends against the workspace's resend limit, so a 429
is quota_exceeded. A window older than 14 days, in the future, or with until before since is
validation_failed.
api-keys-update
Write. PATCH https://api.ken.so/v1/api-keys/{apiKeyId}
Path: apiKeyId
Body (json): apiVersion string
Change the API version one of the caller's keys is pinned to. api_version is a dated version, "1.1", "legacy" or "1.0". The new pin applies to the key's next request.
PATCH /api/v1/api-keys/{apiKeyId} with Ken-Version 1.1 and
X-Ken-Workspace-Id. Internal exposure. Envelope: success plus data, the
key as api_keys(operation="api-keys-list") returns it, with the new
apiVersion.
api_key_id is the key id string (apk_...), never the secret.
api_version (DEV-15): a supported dated version from
contracts/api-versions.json (one whose retiresOn has come is refused, and so
are its aliases), "1.1" (the first dated version), or "legacy"
(today's behavior: no pin, so a call without Ken-Version gets the legacy
shapes; "1.0" means the same and is sent as "legacy"). "legacy" is the way
back for a script that broke after a key was created on the newest version.
A session signed in with a Kenso API key cannot change pins (403
forbidden); only a session signed in with OAuth can. A key the caller does
not own is 404 not_found. Needs the integrations feature in the workspace,
like creating a key, and for a key held to a permission template, in that
template's workspace too (DEV-7503): without it the change is 403
permission_denied, and so is a key whose template was deleted or whose
workspace the caller left (that key works nowhere).