Skip to Content
FlowVerifyDevelopers

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.

PropertyNotes
Prefixfv_live_ (production). fv_test_ keys are reserved for a future test mode and are not issued yet
ScopesChosen at creation, editable later. A key with no scopes can only call GET /me
ExpiryOptional. Expired keys answer 401 invalid_api_key
IP allowlistOptional list of source IPs / CIDRs. Requests from elsewhere answer 403 ip_not_allowed
Rate limitOptional per-key ceiling below the plan default (see limits)
RotationIssues a new key with the same settings; the old one keeps working for 24 hours
RevocationImmediate (within a minute across all servers). Cannot be undone

Scopes

Scopes are resource:action. Write and send scopes imply read.

ScopeGrants
envelopes:readList and read envelopes, status, history, downloads, bulk-send jobs
envelopes:writeCreate and edit drafts: files, recipients, fields; void, hold, resume, archive
envelopes:sendSend, remind, bulk send, send from template
templates:readList and read templates, their roles and fields
templates:writeReserved for template authoring (not yet exposed)
sign_forms:read / sign_forms:writeReserved (not yet exposed)
contacts:read / contacts:writeReserved (not yet exposed)
webhooks:readList webhooks, the event catalogue and the delivery log
webhooks:manageCreate, edit, delete, test, rotate secrets, replay deliveries
org:readRead the organization profile and usage through GET /me
embedded:signReserved 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.

StatuscodeMeaning
401invalid_api_keyMissing, malformed, unknown, revoked, expired or suspended key
403api_access_disabledAPI access is paused for the workspace, or the workspace is inactive
403feature_not_availableThe plan does not include API access
403ip_not_allowedSource IP outside the key's allowlist
403insufficient_scopeKey lacks the scope for this endpoint
429rate_limitedToo many unauthenticated attempts from one IP, or the key's limit was reached
503public_api_disabledThe 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 429 without waiting for Retry-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.

On this page