POST /v1/firm-control/api-keys
operationId: createAPIKey
Creates a new firm API key. The raw secret is returned once in this response and never again.
Headers
| Header | Notes |
|---|---|
X-Firm-ID | Firm UUID. Auto-injected for firm API keys. |
Body
| Field | Required | Notes |
|---|---|---|
name | yes | Human label. |
scopes | no | Array of scope strings. Defaults to the firm’s default scope set. |
expires_at | no | RFC 3339 timestamp. Omit for non-expiring keys. |
Example
curl -X POST "$TRADARA_BASE_URL/v1/firm-control/api-keys" \
-H "X-Tradara-Api-Key: $TRADARA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "prod-orderbot",
"scopes": ["orders:write", "fills:read", "balances:read"],
"expires_at": "2027-01-01T00:00:00Z"
}'
Response — 201 Created
{
"id": "key_01HW...",
"firm_id": "8f4a1d6e-2b1c-4e9a-9d3b-5e6c7a0d1f23",
"name": "prod-orderbot",
"key_prefix": "tdr_live_4f2c8",
"scopes": ["orders:write", "fills:read", "balances:read"],
"status": "ACTIVE",
"created_by_user_id": "usr_01HW...",
"last_used_at": null,
"expires_at": "2027-01-01T00:00:00Z",
"revoked_at": null,
"revoked_by_user_id": null,
"created_at": "2026-06-26T16:00:00Z",
"updated_at": "2026-06-26T16:00:00Z",
"secret": "tdr_live_4f2c8e7b9d3a4c1e8f7d6c5b4a3e2d1c0"
}
secret is shown only in this response. List calls return everything except secret.Errors
| HTTP | Meaning |
|---|---|
400 | Missing name or invalid scope. |
502 | Downstream key service unreachable. |