> ## Documentation Index
> Fetch the complete documentation index at: https://formcarry.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Authentication with Bearer Tokens

> Generate a Formcarry API key, send it as a Bearer token, understand scopes, and verify credentials with GET /v1/me.

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

1. Open your Formcarry dashboard.
2. Go to [**API Keys**](https://app.formcarry.com/api-keys).
3. 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.

<Warning>
  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.
</Warning>

## Send the token

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

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.formcarry.com/v1/me \
    -H "Authorization: Bearer fc_live_your_api_key"
  ```

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

  ```python Python theme={null}
  import os, requests

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

<Note>
  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`.
</Note>

## Verify a key

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

```bash theme={null}
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](/docs/api/overview#errors). 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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.