API Authentication with Bearer Tokens

The Formcarry API authenticates every request with a Bearer token. Keys are scoped to a workspace and carry a fixed set of permissions.

Generate an API key

Open your Formcarry dashboard.
Go to API Keys.
Click Create key, choose the scopes it needs, and copy the key.

Keys are prefixed with fc_live_. Copy the key immediately; it is shown only once.

Treat API keys like passwords. Do not commit them to source control, embed them in client-side code, or share them in support tickets. If a key is exposed, revoke it in the dashboard and issue a new one.

Send the token

Pass the key in the Authorization header on every request using the Bearer scheme.

curl https://api.formcarry.com/v1/me \
  -H "Authorization: Bearer fc_live_your_api_key"

const res = await fetch("https://api.formcarry.com/v1/me", {
  headers: {
    Authorization: `Bearer ${process.env.FORMCARRY_API_KEY}`,
  },
});
const me = await res.json();

import os, requests

res = requests.get(
    "https://api.formcarry.com/v1/me",
    headers={"Authorization": f"Bearer {os.environ['FORMCARRY_API_KEY']}"},
)
me = res.json()

The header name is Authorization, not api_key. The previous api_key header used by the legacy API is no longer accepted on api.formcarry.com.

Verify a key

Call GET /v1/me to confirm a key is valid and inspect the workspace, key ID, and granted scopes it represents.

curl https://api.formcarry.com/v1/me \
  -H "Authorization: Bearer fc_live_your_api_key"

A valid key returns 200 OK with details about the authenticated key. An invalid or revoked key returns 401 with code: "invalid_key", and a missing header returns 401 with code: "missing_bearer".

Scopes

Each key is issued with one or more scopes that gate which endpoints it can call. The four scopes:

Scope	Allows
`forms:read`	List and retrieve forms and their fields.
`forms:write`	Create, update, and delete forms; manage email recipients and images.
`submissions:read`	List and read submissions.
`submissions:write`	Update submission status, mark read/unread, delete submissions.

If a key is missing the required scope for an endpoint, the API returns 403 with code: "insufficient_scope". Create a new key with the correct scopes rather than upgrading an existing key in place.

Errors

Authentication failures use the standard error envelope. The most common codes:

Code	Status	Meaning
`missing_bearer`	401	No `Authorization` header on the request.
`invalid_key`	401	Key is malformed, revoked, or does not exist.
`wrong_audience`	401	Key is not valid for the Formcarry API.
`insufficient_scope`	403	Key is valid but lacks the required scope.
`form_access_restricted`	403	Key cannot access the requested form.
`team_inactive`	403	The workspace is suspended.
`owner_unverified`	403	Account owner must verify their email before this key can be used.

Overview

Endpoints

Legacy API

API Authentication with Bearer Tokens

Generate an API key

Send the token

Verify a key

Scopes

Errors

​Generate an API key

​Send the token

​Verify a key

​Scopes

​Errors

Generate an API key

Send the token

Verify a key

Scopes

Errors