API keys
API key management. Dashboard session only: an API key cannot create or revoke keys.
Set up the SDK client used in the examples
Dashboard session only (API keys get 403 session_required):
import { UpVoiced } from '@upvoiced/sdk';
// Dashboard-session operations: the Clerk session token of a signed-in operator.
const upvoiced = new UpVoiced({
headers: { authorization: `Bearer ${sessionToken}` },
workspace: workspaceId,
});curl examples read $UPVOICED_API_KEY and $UPVOICED_WORKSPACE_IDfrom your shell. MCP examples are the tools/call request an MCP client sends to the MCP server with the same API key.
GET/v1/api-keys
List the workspace's API keys (prefix, scopes, last used; never the key)
| Name | Type | Required |
|---|---|---|
x-workspace | string (uuid) | Yes |
Response 200: 15 fields
| Name | Type | Required |
|---|---|---|
items | array of object | Yes |
items[].id | string (uuid) | Yes |
items[].name | string | Yes |
items[].prefix | stringpattern ^uv_(live|test)_[0-9a-f]{12}$ | Yes |
items[].environment | "live" | "test" | Yes |
items[].scopes | array of "read" | "write" | "admin"items 1–3 | Yes |
items[].access | "workspace" | "all" | Yes |
items[].created_by | object | Yes |
items[].created_by.id | string (uuid) | Yes |
items[].created_by.name | string | Yes |
items[].created_at | string (date-time) | Yes |
items[].expires_at | string (date-time) | null | Yes |
items[].last_used_at | string (date-time) | null | Yes |
items[].revoked_at | string (date-time) | null | Yes |
next_cursor | null | Yes |
Errors: 400, 401, 403, 404, 409, 413, 422, 429, 500, 503, all in the standard error shape.
curl 'https://api.upvoiced.com/v1/api-keys' \
-H "Authorization: Bearer $UPVOICED_SESSION_TOKEN" \
-H "X-Workspace: $UPVOICED_WORKSPACE_ID"const data = await upvoiced.get('/v1/api-keys');No MCP tool for this operation. The MCP server covers the everyday reads and writes.
POST/v1/api-keys
Create an API key; the key is in this response only
| Name | Type | Required |
|---|---|---|
x-workspace | string (uuid) | Yes |
idempotency-key | stringpattern ^[A-Za-z0-9_.:-]{8,128}$ | No |
| Name | Type | Required |
|---|---|---|
name | stringlength 1–100 | Yes |
scope | "read" | "write" | "admin" | Yes |
access | "workspace" | "all"default "workspace" | No |
expires_at | string (date-time) | nulldefault null | No |
Response 201: 14 fields
| Name | Type | Required |
|---|---|---|
id | string (uuid) | Yes |
name | string | Yes |
prefix | stringpattern ^uv_(live|test)_[0-9a-f]{12}$ | Yes |
environment | "live" | "test" | Yes |
scopes | array of "read" | "write" | "admin"items 1–3 | Yes |
access | "workspace" | "all" | Yes |
created_by | object | Yes |
created_by.id | string (uuid) | Yes |
created_by.name | string | Yes |
created_at | string (date-time) | Yes |
expires_at | string (date-time) | null | Yes |
last_used_at | string (date-time) | null | Yes |
revoked_at | string (date-time) | null | Yes |
secret | string | nullpattern ^uv_(live|test)_([0-9a-f]{12})_([0-9A-Za-z]{43})$ | Yes |
Errors: 400, 401, 403, 404, 409, 413, 422, 429, 500, 503, all in the standard error shape.
curl -X POST 'https://api.upvoiced.com/v1/api-keys' \
-H "Authorization: Bearer $UPVOICED_SESSION_TOKEN" \
-H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"name": "Example",
"scope": "read"
}'const data = await upvoiced.post('/v1/api-keys', { body: { name: 'Example', scope: 'read' } });No MCP tool for this operation. The MCP server covers the everyday reads and writes.
DELETE/v1/api-keys/{id}
Revoke an API key (effective on the next request; idempotent)
| Name | Type | Required |
|---|---|---|
id | string (uuid) | Yes |
| Name | Type | Required |
|---|---|---|
x-workspace | string (uuid) | Yes |
Response 200: 13 fields
| Name | Type | Required |
|---|---|---|
id | string (uuid) | Yes |
name | string | Yes |
prefix | stringpattern ^uv_(live|test)_[0-9a-f]{12}$ | Yes |
environment | "live" | "test" | Yes |
scopes | array of "read" | "write" | "admin"items 1–3 | Yes |
access | "workspace" | "all" | Yes |
created_by | object | Yes |
created_by.id | string (uuid) | Yes |
created_by.name | string | Yes |
created_at | string (date-time) | Yes |
expires_at | string (date-time) | null | Yes |
last_used_at | string (date-time) | null | Yes |
revoked_at | string (date-time) | null | Yes |
Errors: 400, 401, 403, 404, 409, 413, 422, 429, 500, 503, all in the standard error shape.
curl -X DELETE 'https://api.upvoiced.com/v1/api-keys/0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d' \
-H "Authorization: Bearer $UPVOICED_SESSION_TOKEN" \
-H "X-Workspace: $UPVOICED_WORKSPACE_ID"const data = await upvoiced.delete('/v1/api-keys/{id}', { path: { id: '0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d' } });No MCP tool for this operation. The MCP server covers the everyday reads and writes.