Authentication
API keys, scopes, rotation, IP allowlists and what a key can never do.
Every request carries a workspace API key as a bearer token:
curl https://api.flowverify.co/v1/envelopes?limit=5 \
-H "Authorization: Bearer fv_live_xxxxxxxx"Keys are accepted only in the Authorization header — never in a query string, cookie or custom header — and only by api.flowverify.co. A key presented to the dashboard API is rejected like any invalid session.
Keys belong to the workspace
Keys are created by a workspace admin under Settings → Developers → API keys. Each key belongs to the workspace, not to the admin who created it: integrations keep working when people leave, and the audit trail shows "API" (with the key id) rather than a person.
| Property | Notes |
|---|---|
| Prefix | fv_live_ (production). fv_test_ keys are reserved for a future test mode and are not issued yet |
| Scopes | Chosen at creation, editable later. A key with no scopes can only call GET /me |
| Expiry | Optional. Expired keys answer 401 invalid_api_key |
| IP allowlist | Optional list of source IPs / CIDRs. Requests from elsewhere answer 403 ip_not_allowed |
| Rate limit | Optional per-key ceiling below the plan default (see limits) |
| Rotation | Issues a new key with the same settings; the old one keeps working for 24 hours |
| Revocation | Immediate (within a minute across all servers). Cannot be undone |
Scopes
Scopes are resource:action. Write and send scopes imply read.
| Scope | Grants |
|---|---|
envelopes:read | List and read envelopes, status, history, downloads, bulk-send jobs |
envelopes:write | Create and edit drafts: files, recipients, fields; void, hold, resume, archive |
envelopes:send | Send, remind, bulk send, send from template |
templates:read | List and read templates, their roles and fields |
templates:write | Reserved for template authoring (not yet exposed) |
sign_forms:read / sign_forms:write | Reserved (not yet exposed) |
contacts:read / contacts:write | Reserved (not yet exposed) |
webhooks:read | List webhooks, the event catalogue and the delivery log |
webhooks:manage | Create, edit, delete, test, rotate secrets, replay deliveries |
org:read | Read the organization profile and usage through GET /me |
embedded:sign | Reserved for embedded signing sessions (not yet exposed) |
A call without the required scope answers 403 insufficient_scope with details.required_scope.
Identify the caller
curl https://api.flowverify.co/v1/me -H "Authorization: Bearer fv_live_xxxxxxxx"{
"success": true,
"data": {
"object": "account",
"organization": { "object": "organization", "id": "…", "name": "Acme Pvt Ltd", "slug": "acme", "timezone": "Asia/Kolkata" },
"api_key": { "object": "api_key", "id": "…", "name": "ERP integration", "prefix": "fv_live_EWSg", "scopes": ["envelopes:send", "templates:read"], "environment": "live", "created_at": "…", "expires_at": null, "last_used_at": "…" },
"plan": { "code": "ENTERPRISE", "name": "Enterprise" },
"usage": { "envelopes": { "used": 120, "limit": 1000 } }
},
"request_id": "…"
}Failure modes
Authentication failures are deliberately uninformative from the outside — the exact reason is recorded on our side for the workspace's security log.
| Status | code | Meaning |
|---|---|---|
| 401 | invalid_api_key | Missing, malformed, unknown, revoked, expired or suspended key |
| 403 | api_access_disabled | API access is paused for the workspace, or the workspace is inactive |
| 403 | feature_not_available | The plan does not include API access |
| 403 | ip_not_allowed | Source IP outside the key's allowlist |
| 403 | insufficient_scope | Key lacks the scope for this endpoint |
| 429 | rate_limited | Too many unauthenticated attempts from one IP, or the key's limit was reached |
| 503 | public_api_disabled | The API is paused for maintenance or an incident. Retry after the Retry-After seconds |
Repeated invalid keys from one IP are throttled and eventually blocked at the edge, so never retry a 401 in a loop.
Automatic suspension
A key is suspended automatically when its traffic looks like abuse rather than an integration:
- a burst of requests for many different resources that don't exist in your workspace, making up most of the key's traffic (for example walking through ids);
- a large volume of requests the key's scopes don't allow;
- thousands of requests that keep arriving after
429without waiting forRetry-After.
Plan-limit and feature errors (plan_limit_exceeded, feature_not_available) never count, and neither does retrying the same missing id.
A suspended key answers 401 invalid_api_key like any invalid key. Your workspace admins get an in-app notification, and Settings → Developers shows the key as Suspended with the reason. Contact [email protected] to have it reinstated. To stay clear of it, honour Retry-After, stop when a record answers 404, and keep each key's scopes matched to what the integration calls.
FlowVerify can also pause API access for a workspace (403 api_access_disabled, admins notified), or for everyone during an incident (503 public_api_disabled with Retry-After).
What a key can never do
- Sign a document on behalf of a recipient. Signing happens in the signer app with the recipient's own consent and verification; the API can create envelopes and, later, short-lived embedded signing sessions.
- Read another workspace's data. A wrong or foreign id answers
404 not_found— the same body as a missing record. - Log in to the dashboard, change billing, members or security settings.
Keep keys safe
- Store keys in a secrets manager, never in source control or client-side code.
- Give each integration its own key with the minimum scopes; revoke keys you no longer use.
- Restrict production keys to your egress IPs.
- Rotate on a schedule. Rotation keeps the old key valid for 24 hours so you can switch without downtime.
- If a key leaks, revoke it in the console immediately; it stops working everywhere within a minute.