> ## 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. |


## Related topics

- [Formcarry API Overview](/docs/api/overview.md)
- [Legacy Formcarry API Overview](/docs/api/legacy/overview.md)
- [Legacy API Authentication](/docs/api/legacy/authentication.md)
- [Check that the API is up](/docs/api-reference/health/check-that-the-api-is-up.md)
- [Legacy Forms API — Create and Delete Forms](/docs/api/legacy/forms.md)