Authentication

Every endpoint under /v2/* except the few listed at the bottom requires a Bearer token.

Get an API key

Self-serve from the developer portal:

Open developer.piratecrew.fun.
Sign in with Google.
Click Generate Key, give it a label, and copy the value immediately. The full key is shown once — store it in your secrets manager.
Manage, revoke, or adjust scopes from the same dashboard.

Each key is backed by a row in the api_keys Supabase table.

Sending the key

Authorization: Bearer <your-api-key>

If you're using the SDK, pass the key once to the constructor — every method attaches the header for you.

Failure	HTTP	`error.code`	Message
Header missing or not `Bearer <key>`	401	`unauthorized`	`Missing or invalid API key`
Key not found or revoked	403	`forbidden`	`Invalid or revoked API key`
Per-minute quota exceeded	429	`rate_limited`	`Too many requests this minute`
Per-day quota exceeded	429	`rate_limited`	`Daily quota exceeded`
Concurrent-write race lost	429	`rate_limited`	`Rate limit exceeded (concurrent)`
Missing required scope (signed-mode endpoints)	403	`forbidden`	`API key missing required scope(s): …`

Errors are wrapped in the standard envelope:

{
  "error": {
    "code": "forbidden",
    "message": "API key missing required scope(s): fees:claim",
    "doc_url": "https://docs.piratecrew.fun/docs/scopes-and-permissions"
  },
  "meta": { "request_id": "req_01HXYZ…" }
}

See Errors & Retries for the full code catalog.

Rate limits

Each key carries its own rate_limit_per_minute and rate_limit_per_day. Counters reset on a rolling window. A 429 response tells you which ceiling tripped — retry with exponential backoff starting at 1 second.

Do not retry 4xx responses other than 429.

Scopes

See Scopes & Permissions.

Idempotency

See Idempotency.

Public endpoints (no key required)

GET /v2/health — liveness probe
GET /v2/openapi.json — live OpenAPI document
GET /v2/docs — Swagger UI
GET /v2/webhook-event-types — webhook event catalog (public read)