Skip to main content
API key management endpoints. These endpoints require Supabase JWT authentication (Dashboard login), not API key authentication.

​
Key concepts

  • API keys are created and managed through the Dashboard or these endpoints
  • The raw key (tp_live_...) is returned only once at creation time — store it securely
  • Keys are SHA-256 hashed before storage and cannot be retrieved later
  • Each key is scoped to one organization with configurable permissions and agent access

​
Data model

FieldTypeDescription
iduuidKey identifier
namestringDisplay name for the key
key_prefixstringFirst characters of the key (for identification)
permissionsarrayList of granted permissions
allowed_agent_idsarrayAgent UUIDs this key can access (null = all)
rate_limit_per_minuteintegerCustom rate limit per minute
rate_limit_per_hourintegerCustom rate limit per hour
is_activebooleanWhether the key is active
last_used_atdatetimeLast request timestamp
expires_atdatetimeExpiration date (null = never)
created_atdatetimeCreation timestamp

​
Available permissions

PermissionAllows
agents:readList and read agent configurations
agents:writeUpdate agent settings
employees:readList and read employees
employees:writeCreate, update, delete employees
tools:readList and read agent tools
tools:writeCreate, update, delete tools
forwarding:readList forwarding slots
forwarding:writeCreate, update, delete, replace slots
kb:readList and read knowledge base documents
kb:writeCreate, update, delete KB documents
calls:readList and read call records
organization:readRead organization settings
organization:writeUpdate organization settings

​
Endpoints

​
List API keys

GET /v1/api-keys
Auth: JWT only Returns all keys for the current user’s organization. Key values are never returned — only the prefix.

​
Create API key

POST /v1/api-keys
Auth: JWT only 
{
  "name": "n8n Production",
  "permissions": ["agents:read", "agents:write", "employees:read", "employees:write"],
  "rate_limit_per_minute": 60,
  "expires_at": null
}
Response includes the raw key (shown only once): 
{
  "key": "tp_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "id": "key-uuid",
  "name": "n8n Production",
  "permissions": ["agents:read", "agents:write", "employees:read", "employees:write"],
  "created_at": "2026-03-22T10:00:00Z"
}

​
Update API key

PATCH /v1/api-keys/{keyId}
Auth: JWT only Update name, permissions, rate limits, or active status. The key value cannot be changed. 
# Restrict to read-only
curl -X PATCH -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
  -d '{"name": "n8n Read-Only", "permissions": ["agents:read", "employees:read", "calls:read"]}' \
  "$TP_BASE/api-keys/{keyId}"

​
Revoke API key

DELETE /v1/api-keys/{keyId}
Auth: JWT only | Returns 204 No Content Permanently deletes the key. Any requests using this key will immediately receive 401 Unauthorized.

​
Key rotation workflow

  1. Create a new key with the same permissions
  2. Update your integration to use the new key
  3. Verify the integration works
  4. Delete the old key