First steps
Authentication
PromptFloe authenticates every API request via a workspace-scoped API key passed as a Bearer token. Keys inherit the workspace's tier, quotas, and member permissions.
#Auth scheme
All requests use HTTP Bearer auth. Pass your API key in the Authorization header on every request. The SDK does this for you when you initialize a client.
Header
Authorization: Bearer pf_live_********************************#Key formats
| Field | Type | Description |
|---|---|---|
| pf_live_… | production | Live keys. Counted against your real quotas. Use these in production. |
| pf_test_… | sandbox | Test keys. Calls hit a simulator; no real builds run, no quotas consumed. |
| pf_dev_… | local | Dev keys. Same powers as live but rate-limited harder. For local development. |
#Generating a key
- Open
/settings/api. - Click + New API key.
- Name it (e.g. "production-server", "ci-runner").
- Pick scopes (see below).
- Copy the key — we show it once and never again.
#Scopes
Each key has scopes that limit what it can do. Default new keys get read + build; admin actions require an explicit opt-in.
| Field | Type | Description |
|---|---|---|
| read | scope | GET endpoints — list apps, read chats, fetch deployment status. |
| build | scope | Generate apps, run skills, run augmenters, edit files. |
| deploy | scope | Trigger Netlify deploys, manage GitHub sync. |
| admin | scope | Manage workspace context, custom skills, members, billing. |
| webhook:write | scope | Create / update webhook subscriptions. |
#Using the key
const client = new PromptFloe({
apiKey: process.env.PROMPTFLOE_API_KEY,
});#Rotation
Best practice: rotate keys every 90 days, or whenever a contributor leaves the workspace. The dashboard supports graceful rotation:
- Create a new key.
- Roll out the new key to all consumers.
- Click Mark as superseded on the old key — it stays valid for 24 hours but appears as deprecated in logs.
- After 24 hours, click Revoke.
#Auth errors
| Field | Type | Description |
|---|---|---|
| 401 invalid_key | auth | Key is malformed, revoked, or doesn't exist. |
| 401 expired_key | auth | Key was rotated and the grace period ended. |
| 403 missing_scope | auth | Key is valid but lacks a scope required for this endpoint. |
| 403 quota_exceeded | tier | Workspace hit a daily limit. Upgrade tier or wait for reset. |
Every error response includes the request id (X-Request-Id header) — quote it when contacting support.
#Security best practices
- Never embed live keys in client-side code. Use a thin server proxy or short-lived session tokens (see Sessions docs).
- Restrict scopes per environment — the CI key shouldn't need
admin; the prod app server probably doesn't needwebhook:write. - Set up an alert on
401 invalid_keyspikes — those usually mean leaked-key probes. - Use
pf_test_keys in CI to avoid burning quota on tests.
#Where to go next
PromptFloe developer docs