API Keys

Create Key

Generate a new API key.

The raw key is returned ONCE in the response. Only the SHA-256 hash is stored in the database.

Closed-beta gating (CLOSED_BETA_MODE=true, default): only users who already hold an ACTIVE admin-issued key — i.e. cohort members admitted via POST /admin/api-keys/issue or /admin/api-keys/issue-beta — can self-service additional keys. Admins themselves bypass the gate. A waitlisted user with no key yet receives a 403 CLOSED_BETA envelope pointing at the apply URL.

POST

keys

Create Key

curl --request POST \
  --url https://api.polysimulator.com/v1/keys \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "<string>",
  "tier": "free",
  "permissions": [
    "<string>"
  ]
}
'

{
  "id": 123,
  "raw_key": "<string>",
  "key_prefix": "<string>",
  "rate_limit_tier": "<string>",
  "permissions": [
    "<string>"
  ],
  "created_at": "<string>",
  "name": "<string>"
}

Authorizations

X-API-Key

string

header

required

Issue from /v1/keys (or admin-issued for enterprise tier).

Headers

authorization

string | null

X-API-Key

string | null

POLY_API_KEY

string | null

Poly-API-Key

string | null

Body

application/json

name

string | null

Human-readable label

Maximum string length: 100

tier

string

default:free

Rate limit tier: free, pro, enterprise

permissions

string[] | null

Permissions: read, trade, admin

Response

Successful Response

Returned once on creation — the raw key is NOT stored.

integer

required

raw_key

string

required

key_prefix

string

required

rate_limit_tier

string

required

permissions

string[]

required

created_at

string

required

name

string | null

Bootstrap first API key via Bearer JWT (advanced / headless)Create your **first** API key using a Supabase Bearer access token. Most users don't call this endpoint directly — the dashboard at [polysimulator.com/api-keys](https://polysimulator.com/api-keys) handles the JWT exchange transparently. This endpoint exists for headless / CI setups where there's no browser session: `POST /v1/keys` requires an existing `X-API-Key`, but a fresh user has no key yet. **Auth:** `Authorization: Bearer <supabase_access_token>` from a programmatic Supabase sign-in. Verified HS256 against `SUPABASE_JWT_SECRET` with `audience="authenticated"`; expiry and `sub` UUID enforced. **Limits:** 1 call/minute, 5 calls/hour per IP — real users only bootstrap once per account. Returns `400 BOOTSTRAP_NOT_ALLOWED` if you already have API key(s); use `POST /v1/keys` for additional keys.

Create Key

curl --request POST \
  --url https://api.polysimulator.com/v1/keys \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "<string>",
  "tier": "free",
  "permissions": [
    "<string>"
  ]
}
'

{
  "id": 123,
  "raw_key": "<string>",
  "key_prefix": "<string>",
  "rate_limit_tier": "<string>",
  "permissions": [
    "<string>"
  ],
  "created_at": "<string>",
  "name": "<string>"
}