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:
| Type | Prefix | Scopes | Authenticates |
|---|---|---|---|
mcp | sk_ | MCP tool scopes, e.g. read:audience, trigger:sync | The MCP server |
rest_api | rk_ | RBAC permissions — see REST API keys | The REST API (/api/v1) |
serving | svk_ | serve:profile | The 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).
| Method | Path | Description |
|---|---|---|
GET | /api/v1/workspaces/{id}/api-keys | List MCP keys (add ?type=rest_api or ?type=serving for the others) |
POST | /api/v1/workspaces/{id}/api-keys | Create 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
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Display name for the API key |
scopes | string[] | Yes | At 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. |
type | string | No | mcp (default), rest_api, or serving |
expires_at | string | No | RFC3339 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
| Parameter | Type | Description |
|---|---|---|
id | string (UUID) | Workspace ID |
keyId | string (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
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Unique identifier |
workspace_id | string (UUID) | Workspace the key belongs to |
name | string | Display name |
type | string | mcp (sk_), rest_api (rk_), or serving (svk_) |
raw_key | string | Raw key value (only in creation response) |
key_prefix | string | First few characters of the key for identification |
scopes | string[] | Scopes granted to the key |
created_by | string (UUID) | Account that created the key |
last_used_at | string (ISO 8601) or null | When the key was last used |
expires_at | string (ISO 8601) or null | Expiry timestamp, or null if it never expires |
created_at | string (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.