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

# Authentication

> Create test and live API keys and send them with every request.

Authenticate every request with an API key in the `x-api-key` header.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.fawcos.com/v1/relying-party/me \
    -H "x-api-key: $FAWCOS_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch('https://api.fawcos.com/v1/relying-party/me', {
    headers: { 'x-api-key': process.env.FAWCOS_API_KEY },
  });
  const { data } = await res.json();
  ```

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

  res = requests.get(
      "https://api.fawcos.com/v1/relying-party/me",
      headers={"x-api-key": os.environ["FAWCOS_API_KEY"]},
  )
  data = res.json()["data"]
  ```
</CodeGroup>

<Note>The host `api.fawcos.com` is a placeholder until the production host is announced.</Note>

## Test and live keys

| Prefix | Environment | What it can reach |
| - | - | - |
| `FWS_test_` | Test (sandbox) | Synthetic farmers only. No real person's data. |
| `FWS_live_` | Live | Real farmers who have consented to share with your organisation. |

The prefix is part of the key and decides the environment. A test key can never return a real
farmer's data, and a live key can never return a synthetic one. Test and live keys are
separate: a key from one environment does not work in the other.

Keys issued before the `FWS_` prefix (they start `fawcos_test_` or `fawcos_live_`) keep working
until you rotate them.

## Who can create keys

Organisation administrators create and manage keys in the FaWCOS enterprise dashboard.

| Environment | When you can create a key |
| - | - |
| Test | Once you turn on sandbox access for your organisation. |
| Live | Once your compliance application is approved. See [Go live](/go-live). |

Each key has a name and one or more [scopes](/permissions). You can hold up to five active keys
per environment, for example one per system.

## Handling keys

<Warning>
  A key is shown **once**, when you create it. FaWCOS stores only a hash, so a lost key cannot be
  recovered: create a new one.
</Warning>

* Store keys in a secrets manager or environment variable. Never put them in source control, logs,
  screenshots, support tickets, mobile apps or browser code.
* Give each system its own key with the narrowest scopes it needs.
* Never use a live key where a test key will do.

## Rotating and revoking

* **Rotate.** Rotating creates a replacement with the same name, scopes and limits. The old key
  keeps working for an overlap you choose (60 minutes by default, up to 7 days) so you can deploy
  the new one without downtime. Set the overlap to 0 to end the old key at once.
* **Revoke.** A revoked key stops working immediately.
* If you suspect a key has leaked, revoke it first and create a new one.

## Authentication errors

| Status | `code` | Cause |
| - | - | - |
| 401 | `unauthorized` | The `x-api-key` header is missing, malformed, unknown, revoked or expired. |
| 403 | `live_access_not_approved` | A live key was used before your organisation was approved for live access, or while access is suspended. |
| 403 | `access_denied` | Your organisation is not active. |
| 403 | `insufficient_scope` | The key is valid but does not hold the scope the endpoint needs. |

A rejected key never says which part was wrong. See [Errors](/guides/errors) for the full list.


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