API Keys

​

Quick facts

• API keys are workspace scoped, not global credentials.
• API key management uses JWT-authenticated workspace APIs.
• Public Agent API calls use the API key itself.
• Plaintext key material is returned only once at creation time.
• Expired keys no longer authorize requests and do not count toward the active-key quota.
• If the key creator is no longer an active workspace member, the key becomes invalid.

​

Key format and transport

trsq_live_<keyId>_<secret>

x-api-key: trsq_live_<keyId>_<secret>

Authorization: Bearer trsq_live_<keyId>_<secret>

​

Status model

​

Role and scope model

​

Accepted roles

• viewer
• member

• scope controls which API surfaces are available
• role controls effective permissions inside the workspace
• a viewer key can still be rejected on write endpoints even if write scopes were requested

​

Scopes

​

Active-key quota

• revokedAt = null
• and expiresAt is either null or still in the future

• expired keys do not block replacement keys
• revoked keys do not count toward the quota

​

Management API for API keys

Authorization: Bearer <supabase_jwt>

/workspaces/:workspaceId/api-keys

​

List API keys

GET /workspaces/:workspaceId/api-keys

{
  "data": [
    {
      "id": "api_key_123",
      "name": "agent-prod",
      "description": "Production key for autonomous research agent",
      "role": "member",
      "scopes": [
        "workspace_read",
        "system_strategies_read",
        "strategies_read",
        "strategies_write",
        "backtests_read",
        "backtests_write"
      ],
      "keyPrefix": "trsq_live_abcd1234",
      "tokenPreview": "trsq_live_abcd1234_...",
      "status": "active",
      "lastUsedAt": "2026-03-19T08:20:00.000Z",
      "expiresAt": "2026-12-31T23:59:59.000Z",
      "revokedAt": null,
      "createdAt": "2026-03-19T08:00:00.000Z",
      "createdBy": {
        "id": "user_123",
        "email": "owner@example.com",
        "name": "Workspace Owner"
      }
    }
  ]
}

​

Create an API key

POST /workspaces/:workspaceId/api-keys

{
  "name": "agent-prod",
  "description": "Production key for autonomous research agent",
  "role": "member",
  "scopes": [
    "workspace_read",
    "system_strategies_read",
    "strategies_read",
    "strategies_write",
    "backtests_read",
    "backtests_write"
  ],
  "expiresAt": "2026-12-31T23:59:59.000Z"
}

• name: required, 1-100 chars
• description: optional, up to 500 chars
• role: optional, member or viewer
• scopes: optional, but if provided it must contain at least one scope
• expiresAt: optional, but must be a future datetime

• default role is member
• default scopes are the full public-agent set used by write-capable workflows

{
  "id": "api_key_123",
  "name": "agent-prod",
  "description": "Production key for autonomous research agent",
  "role": "member",
  "scopes": [
    "workspace_read",
    "system_strategies_read",
    "strategies_read",
    "strategies_write",
    "backtests_read",
    "backtests_write"
  ],
  "keyPrefix": "trsq_live_abcd1234",
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "createdAt": "2026-03-19T08:00:00.000Z",
  "apiKey": "trsq_live_abcd1234_super_secret_value"
}

• apiKey is returned once, at creation time only
• the database stores a hash, not the plaintext secret

​

Revoke an API key

DELETE /workspaces/:workspaceId/api-keys/:apiKeyId

{
  "success": true,
  "revokedAt": "2026-03-19T09:00:00.000Z"
}

• revoke takes effect immediately
• repeated revoke calls are idempotent and still return success

​

Using an API key with the Public Agent API

/public/v1

​

Recommended first request

GET /public/v1/workspace

• which workspace the key belongs to
• the effective role
• granted scopes
• subscription-tier constraints that may affect behavior

curl -s \
  -H "x-api-key: $TRASEQ_API_KEY" \
  https://api.traseq.com/public/v1/workspace

​

Minimal workflows

​

Read-only agent

1. GET /public/v1/workspace
2. GET /public/v1/system-strategies
3. GET /public/v1/strategies
4. GET /public/v1/backtests

[
  "workspace_read",
  "system_strategies_read",
  "strategies_read",
  "backtests_read"
]

​

Write-capable agent

1. GET /public/v1/workspace
2. POST /public/v1/strategies/validate
3. POST /public/v1/strategies
4. POST /public/v1/strategies/:id/versions/finalize
5. POST /public/v1/backtests
6. GET /public/v1/backtests/:id to poll for results

[
  "workspace_read",
  "strategies_write",
  "strategies_read",
  "backtests_write",
  "backtests_read"
]

​

Common failures

​

401 Unauthorized

• missing x-api-key
• malformed Authorization: Bearer ...
• invalid key format
• revoked key
• expired key
• key creator is no longer a workspace member

Missing API key. Provide x-api-key or Authorization: Bearer <api_key>.

Invalid API key

API key has been revoked

API key has expired

API key creator is no longer a workspace member

​

403 Forbidden

• insufficient scopes
• insufficient role, such as a viewer key calling a write endpoint
• active-key quota reached during key creation

API key limit (5) reached. Revoke unused keys or upgrade your plan.

​

404 Not Found

• DELETE /workspaces/:workspaceId/api-keys/:apiKeyId points to a missing key

​

Best practices

​

For developers

• Store API keys in a secret manager — treat them like passwords.
• Create one key per agent or environment; don’t share keys.
• Use viewer role with read scopes for read-only workflows.
• Use member role for agents that create strategies or run backtests.
• Set an expiration date when possible instead of leaving keys open-ended.
• Revoke keys you’re no longer using.

​

For AI agents

• Always call GET /public/v1/workspace first to confirm your context.
• Validate payloads with POST /public/v1/strategies/validate before writing.
• Don’t assume backtests finish synchronously — poll with GET /public/v1/backtests/:id.
• Use only /public/v1 endpoints for agent workflows.
• When handling errors, check the HTTP status code first, then the response message.

​

Related docs

• API Overview
• Authentication