curl --request POST \
--url https://api.tryhamsa.com/v1/projects/api-keys \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Backend server",
"kind": "SECRET",
"type": "ROOT"
}
'{
"success": true,
"message": "success",
"data": {
"id": "3f6c1a2e-8b4d-4e9a-9c1f-2a7d5e8b0c34",
"name": "Backend server",
"kind": "SECRET",
"type": "SCOPED",
"scopes": [
"agents:read",
"agents:call",
"phone_numbers:read",
"phone_numbers:update",
"call_history:read",
"call_history:monitor"
],
"allowedDomains": [
"example.com"
],
"environment": null,
"publicValue": "pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"secretLast4": "xxxx",
"agentIds": [
"8a1d2c3b-4e5f-4a6b-9c7d-0e1f2a3b4c5d"
],
"expiredAt": "2027-12-31T23:59:59.999Z",
"previousValidUntil": null,
"lastUsedAt": "2026-11-03T09:15:00.000Z",
"previousLastUsedAt": null,
"ref": "key_9f2c4e1a7b3d5f6081a2c3d4e5f60718",
"isDefault": false,
"createdAt": "2026-11-03T09:15:00.000Z",
"updatedAt": "2026-11-03T09:15:00.000Z",
"status": "VALID",
"isValid": true,
"projectId": "fbb9e8b2-2dbb-40f9-a051-9404624e3247",
"secret": "sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}{
"code": 5409,
"message": "This API key was already revoked.",
"messageKey": "ApiKeyAlreadyRevoked",
"params": {
"action": "api_keys:revoke"
}
}{
"code": 8404,
"message": "Policy not found!",
"messageKey": "PolicyNotFound",
"params": {
"reason": "NO_DRAFT"
}
}{
"code": 5409,
"message": "This API key was already revoked.",
"messageKey": "ApiKeyAlreadyRevoked",
"params": {
"action": "api_keys:revoke"
}
}{
"code": 5409,
"message": "This API key was already revoked.",
"messageKey": "ApiKeyAlreadyRevoked",
"params": {
"action": "api_keys:revoke"
}
}{
"code": 5409,
"message": "This API key was already revoked.",
"messageKey": "ApiKeyAlreadyRevoked",
"params": {
"action": "api_keys:revoke"
}
}Create API Key
Creates a key owned by you in the project. Pick the kind by where the key lives: SECRET for servers, PUBLIC for web pages and apps that only start calls. A secret key’s value is in secret in this response only: save it now. A public key’s value is in publicValue. ROOT: everything your role in the project allows (scopes ["*"]). SCOPED: only the scopes you list, and never more than your role allows. Public keys are always SCOPED with ["agents:call"].
curl --request POST \
--url https://api.tryhamsa.com/v1/projects/api-keys \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Backend server",
"kind": "SECRET",
"type": "ROOT"
}
'{
"success": true,
"message": "success",
"data": {
"id": "3f6c1a2e-8b4d-4e9a-9c1f-2a7d5e8b0c34",
"name": "Backend server",
"kind": "SECRET",
"type": "SCOPED",
"scopes": [
"agents:read",
"agents:call",
"phone_numbers:read",
"phone_numbers:update",
"call_history:read",
"call_history:monitor"
],
"allowedDomains": [
"example.com"
],
"environment": null,
"publicValue": "pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"secretLast4": "xxxx",
"agentIds": [
"8a1d2c3b-4e5f-4a6b-9c7d-0e1f2a3b4c5d"
],
"expiredAt": "2027-12-31T23:59:59.999Z",
"previousValidUntil": null,
"lastUsedAt": "2026-11-03T09:15:00.000Z",
"previousLastUsedAt": null,
"ref": "key_9f2c4e1a7b3d5f6081a2c3d4e5f60718",
"isDefault": false,
"createdAt": "2026-11-03T09:15:00.000Z",
"updatedAt": "2026-11-03T09:15:00.000Z",
"status": "VALID",
"isValid": true,
"projectId": "fbb9e8b2-2dbb-40f9-a051-9404624e3247",
"secret": "sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}{
"code": 5409,
"message": "This API key was already revoked.",
"messageKey": "ApiKeyAlreadyRevoked",
"params": {
"action": "api_keys:revoke"
}
}{
"code": 8404,
"message": "Policy not found!",
"messageKey": "PolicyNotFound",
"params": {
"reason": "NO_DRAFT"
}
}{
"code": 5409,
"message": "This API key was already revoked.",
"messageKey": "ApiKeyAlreadyRevoked",
"params": {
"action": "api_keys:revoke"
}
}{
"code": 5409,
"message": "This API key was already revoked.",
"messageKey": "ApiKeyAlreadyRevoked",
"params": {
"action": "api_keys:revoke"
}
}{
"code": 5409,
"message": "This API key was already revoked.",
"messageKey": "ApiKeyAlreadyRevoked",
"params": {
"action": "api_keys:revoke"
}
}Authorizations
Query Parameters
Body
SECRET (sk_...): for servers. The value is shown once, in the response that creates or rotates the key; requests that carry an Origin header (browsers) are refused. PUBLIC (pk_...): for web pages and apps. It can only create call tokens (POST /v1/voice-agents/call-token), for one environment, and its value can be read again at any time. LEGACY: the older kind, whose key ID is also its value. New legacy keys are being retired: when they are turned off, creating one returns LegacyApiKeysRetired.
LEGACY, PUBLIC, SECRET "SECRET"
What a SCOPED key may do. Each item is a preset name, resource:action, resource:* (every action on a resource) or *:action (an action on every resource); presets are expanded when saved. Scopes your role does not have are refused (403). Presets: calls_only, campaigns_only, transcription_only, tts_only, ai_content_only, translate_only, realtime_only (see GET /v1/projects/api-keys/scope-presets). Resources and their actions: agents: create, read, update, delete, export, import, call; knowledge_base: create, read, update, delete, cancel; policies, guardrails, functions_macros: create, read, update, delete, assign; tools, phone_numbers, voices, secrets, voice_overs, transcription: create, read, update, delete; call_history: read, delete, export, monitor; outbound_calls: create, read, update, delete, launch, stop; project: read, update, delete, deactivate; members: read, invite, update, delete; billing: read, update; statistics: read; translate: create, read; tts: create, read, delete; realtime: create, read. GET /v1/projects/api-keys/scopes-schema lists the ones your role allows. Required when type is SCOPED. Ignored for public keys.
1["calls_only"]
Was this page helpful?