Skip to Content
API ReferenceMCP & Serving Keys

MCP & Serving API Keys

This resource manages the workspace’s secret credentials. All of them are hashed at rest, returned in full exactly once at creation, may be given an expiry, and can be revoked at any time. They differ in what they authenticate:

TypePrefixScopesAuthenticates
mcpsk_MCP tool scopes, e.g. read:audience, trigger:syncThe MCP server
rest_apirk_RBAC permissions — see REST API keysThe REST API (/api/v1)
servingsvk_serve:profileThe Profile API — attributes, and member audiences on request

Each type is accepted on its own surface and nowhere else. A credential presented to a surface it does not belong to is refused 401 on the class of the key, before its scopes are considered — so widening an sk_ key’s scopes can never make it read a profile or call the REST API.

read:store and read:membership are MCP tool scopes only. They gate the store and membership tools an agent may invoke over JSON-RPC. Neither authorises an HTTP read: the Profile API takes a serving key with serve:profile, and the Membership API takes a public membership key (pk_), which is a different resource entirely — see below.

Endpoints

The same endpoints manage every key type; pass ?type=rest_api or ?type=serving, or omit it for MCP keys (the default).

MethodPathDescription
GET/api/v1/workspaces/{id}/api-keysList MCP keys (add ?type=rest_api or ?type=serving for the others)
POST/api/v1/workspaces/{id}/api-keysCreate a new API key. Only a signed-in person can create keys; a request made with an API key is refused with 403 and "code": "api_key_not_allowed"
DELETE/api/v1/workspaces/{id}/api-keys/{keyId}Revoke an API key

Membership keys are not managed here. The Membership API’s pk_ credential is public rather than secret — stored in the clear, readable for as long as it exists, and never expiring — so it is a separate resource under /api/v1/workspaces/{id}/membership-keys. Create and revoke them on Personalize → Membership → API keys.


List API Keys

GET /api/v1/workspaces/{id}/api-keys

Returns all API keys for the workspace. The raw key value is never returned in list responses — only the key_prefix is shown for identification.

Response

[ { "id": "550e8400-e29b-41d4-a716-446655440000", "workspace_id": "660e8400-e29b-41d4-a716-446655440000", "name": "CI/CD Pipeline Key", "type": "mcp", "key_prefix": "sk_abc12", "scopes": ["read:audience", "trigger:sync"], "created_by": "770e8400-e29b-41d4-a716-446655440000", "last_used_at": "2024-01-16T11:00:00Z", "expires_at": null, "created_at": "2024-01-15T09:30:00Z" } ]

Example

curl -X GET https://agentic.zeotap.com/api/v1/workspaces/{id}/api-keys \ -H "Authorization: Bearer <token>" \ -H "X-Workspace-ID: <workspace-id>"

Create API Key

POST /api/v1/workspaces/{id}/api-keys

Creates a new API key for the workspace. The raw key value is returned only once in the creation response. Store it securely — it cannot be retrieved again.

Request Body

FieldTypeRequiredDescription
namestringYesDisplay name for the API key
scopesstring[]YesAt least one scope, from the vocabulary of the key’s type. MCP keys use tool scopes (e.g. read:audience, trigger:sync), each of which the creator’s role must support — a scope with none of its permissions held is refused 400 naming the permission; REST API keys use RBAC permissions; serving keys use serve:profile.
typestringNomcp (default), rest_api, or serving
expires_atstringNoRFC3339 timestamp or YYYY-MM-DD date. Omit for a key that never expires
{ "name": "CI/CD Pipeline Key", "scopes": ["read:audience", "trigger:sync"] }

Response

{ "id": "550e8400-e29b-41d4-a716-446655440000", "workspace_id": "660e8400-e29b-41d4-a716-446655440000", "name": "CI/CD Pipeline Key", "type": "mcp", "raw_key": "sk_abc123def456ghi789...", "key_prefix": "sk_abc12", "scopes": ["read:audience", "trigger:sync"], "created_by": "770e8400-e29b-41d4-a716-446655440000", "expires_at": null, "created_at": "2024-01-15T09:30:00Z" }

The raw_key field is only returned in the creation response. Copy and store it securely immediately. If you lose the key, you must revoke it and create a new one.

Example

curl -X POST https://agentic.zeotap.com/api/v1/workspaces/{id}/api-keys \ -H "Authorization: Bearer <token>" \ -H "X-Workspace-ID: <workspace-id>" \ -H "Content-Type: application/json" \ -d '{ "name": "CI/CD Pipeline Key", "scopes": ["read:audience", "trigger:sync"] }'

Revoke API Key

DELETE /api/v1/workspaces/{id}/api-keys/{keyId}

Permanently revokes an API key. Once revoked, any requests using this key will receive a 401 Unauthorized response. This action cannot be undone.

Path Parameters

ParameterTypeDescription
idstring (UUID)Workspace ID
keyIdstring (UUID)API key ID to revoke

Response

{ "status": "revoked" }

Example

curl -X DELETE https://agentic.zeotap.com/api/v1/workspaces/{id}/api-keys/{keyId} \ -H "Authorization: Bearer <token>" \ -H "X-Workspace-ID: <workspace-id>"

API Key Object

FieldTypeDescription
idstring (UUID)Unique identifier
workspace_idstring (UUID)Workspace the key belongs to
namestringDisplay name
typestringmcp (sk_), rest_api (rk_), or serving (svk_)
raw_keystringRaw key value (only in creation response)
key_prefixstringFirst few characters of the key for identification
scopesstring[]Scopes granted to the key
created_bystring (UUID)Account that created the key
last_used_atstring (ISO 8601) or nullWhen the key was last used
expires_atstring (ISO 8601) or nullExpiry timestamp, or null if it never expires
created_atstring (ISO 8601)Creation timestamp

Best Practices

  • Name keys descriptively — Use names like “Production Sync Service” or “CI/CD Pipeline” so you can identify each key’s purpose.
  • One key per integration — Create separate keys for each system that needs API access. This makes it easy to revoke access for a single integration without affecting others.
  • Rotate regularly — Create a new key, update your integration, then revoke the old key.
  • Store securely — Use environment variables or a secrets manager. Never commit API keys to version control.
Last updated on