API authentication
Authenticate the public API with bearer account API keys and understand rate limits.
API reference
API authentication
PreFlight public API v1 uses bearer account API keys. Keys are created by the workspace owner from Dashboard → Settings → API keys and inherit that owner's project access.
Browser sessions continue to use Supabase Auth and workspace-aware RLS. Automation, CI, status bots, and the MCP server use API keys exclusively.
Create a key
- Open Settings → API keys as a workspace owner.
- Name the key for its purpose (for example
github-actions-deploy-gate). - Copy the raw key immediately. PreFlight shows it once, then stores only a SHA-256 hash and prefix.
- Store the key in your CI secret manager or MCP host configuration — never commit it to git.
Header format
Every authenticated request must include:
Authorization: Bearer pf_live_...
Content-Type: application/json
Keys must match the pattern pf_live_ followed by at least 32 alphanumeric characters.
Scope and access
| Rule | Behavior |
|---|---|
| Ownership | Keys belong to the creating user account |
| Project access | Limited to projects that user can control in the workspace |
| Rotation | Create a new key, update consumers, then revoke the old key |
| Browser | Dashboard routes do not accept API keys; use Supabase session cookies |
Idempotent writes
Retried POST requests — especially check triggers from CI — should send a stable idempotency header:
Idempotency-Key: ci-run-2026-06-13-main-001
PreFlight deduplicates on that key so a network retry does not spawn duplicate check runs.
Rate limiting
| Limit type | Behavior |
|---|---|
| Per-key throughput | Applied on all /api/v1/* routes |
| Per-project checks | Additional guardrails on expensive check triggers |
| Failed auth | Independently rate limited from successful traffic |
| Payload size | Oversized JSON bodies rejected before deeper processing |
When limited, the API returns 429 with retry guidance. Automation should backoff exponentially.
Core endpoints
/api/v1/projectsList projects visible to the key. Use this to discover UUIDs in CI.
/api/v1/projects/:projectId/checksTrigger a full pre-flight run. Returns runId, aggregate status, and probe rows.
/api/v1/projects/:projectId/checks/:runIdPoll a specific run until probes finish.
/api/v1/projects/:projectId/deploy-gate?mode=strictEvaluate deploy readiness. Returns allowed and blocking reasons.
See the full catalog in the API overview.
Example: trigger a check
curl -X POST \
-H "Authorization: Bearer pf_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ci-run-2026-06-13-001" \
https://getpreflight.dev/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/checks
Example response
{
"runId": "8b3f2c1a-9d4e-4f5a-b6c7-1234567890ab",
"status": "warning",
"summary": "11 passed, 1 warning, 0 failed.",
"counts": { "success": 11, "warning": 1, "failed": 0 },
"results": []
}
Operational security
Treat API keys like production secrets. Scope CI keys to deploy-gate and check routes only by rotating keys when personnel change.