Create an API key
Create a user-bound key for this workspace. The raw secret is returned exactly once.
API 2.7.0 · Published service contract ↗
Request
Base URL: https://app.sym.so/v1/workspaces/{workspace_id}
Authentication: bearer. Required scope: api_keys:write.
POST /api-keys
Create a user-bound key for this workspace. The raw secret is returned exactly once.
| Parameter | Type | Description |
|---|---|---|
namebody · required | string | Human-readable key name. |
scopesbody · required | string[] | Requested API scopes, capped by the user's permissions. |
expires_atbody | ISO timestamp | null | Optional expiry. |
curl --fail-with-body -X POST "https://app.sym.so/v1/workspaces/$WORKSPACE_ID/api-keys" \
-H "Authorization: Bearer $SYM_WORKSPACE_API_KEY" \
-H "Content-Type: application/json" \
--data "{\"name\":\"Local integration\",\"scopes\":[\"agents:read\",\"files:read\",\"files:write\",\"chats:read\",\"messages:read\",\"messages:send\"],\"expires_at\":null}"{
"worker_id": "worker-example-001",
"org_id": "workspace_example",
"item": {
"id": "key_01J8",
"name": "Local integration",
"scopes": [
"agents:read",
"files:read",
"files:write",
"chats:read",
"messages:read",
"messages:send"
]
},
"key": "sym_ws_x7K2...9Qpf",
"reveal_once": true,
"ok": true
}Authorization
{
"type": "bearer",
"scope": "api_keys:write",
"transport": "Authorization: Bearer <workspace_api_key>"
}Errors
| Status | Description |
|---|---|
| 400 | The request body or parameters are invalid. |
| 401 | The workspace API key is missing, invalid, expired, or revoked. |
| 403 | The key lacks the required scope or its owner no longer has permission. |
| 429 | The key exceeded its current rate limit. |
Usage notes
- SYM-node stores only a one-way hash, key prefix, and last four characters.
- The new key must be owned by the same user and may only receive scopes the caller already holds.
- The raw key must not be logged and cannot be recovered later.