Skip to main content
POST /api/v1/projects/{project_id}/api-keys Requires api_keys.write permission.
The plaintext secret is returned only once in the response. Store it immediately — it cannot be retrieved again. If you lose it, rotate the key to generate a new one.

​
Path parameters

​
project_id
string
required
UUID of the project.

​
Request body

​
environment_id
string
required
UUID of the environment this key will be scoped to.
​
name
string
required
Display name for the key. Example: Production Server Key.
​
scope
string
required
Key scope. One of server, sdk, or stream.
​
expires_at
string | null
ISO 8601 datetime when the key expires. Pass null for a non-expiring key.

​
Response

​
api_key
object
required
Metadata for the created API key.
​
secret
string
required
The full plaintext API key. Shown only once — store it immediately.

​
Errors

StatusWhen
400Request body is invalid or missing required fields
401Missing or invalid Bearer token
403Caller lacks api_keys.write permission

​
Example

curl -X POST http://localhost:8080/api/v1/projects/p1b2c3d4-e5f6-7890-abcd-ef1234567890/api-keys \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"environment_id": "e1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Production Server Key", "scope": "server"}'

{
  "api_key": {
    "id": "k1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "project_id": "p1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "environment_id": "e1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Production Server Key",
    "scope": "server",
    "key_prefix": "tgl_srv_abc123",
    "last_used_at": null,
    "last_used_ip": null,
    "expires_at": null,
    "revoked_at": null,
    "created_at": "2026-03-21T10:00:00Z",
    "updated_at": "2026-03-21T10:00:00Z"
  },
  "secret": "tgl_srv_abc123xyz789..."
}

Build docs developers (and LLMs) love

Get started for freeTalk to us