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

# Authentication

> How to create API keys and authenticate requests to the FormFlows.ai API.

The FormFlows.ai API uses API keys for authentication. Every request must include your key in the `Authorization` header as a Bearer token.

```http theme={null}
Authorization: Bearer sk_live_your_api_key
```

## Creating an API key

<Steps>
  <Step title="Open your dashboard settings">
    Log in to [app.formflows.ai](https://app.formflows.ai) and click your account name in the top-right corner, then select **Settings**.
  </Step>

  <Step title="Navigate to API Keys">
    In the left sidebar, click **API Keys**.
  </Step>

  <Step title="Create a new key">
    Click **Create Key**, give it a descriptive name (e.g., `production-backend` or `data-export-script`), and choose a scope.
  </Step>

  <Step title="Copy your key">
    The key is displayed once immediately after creation. Copy it to a secure location — you will not be able to view it again.
  </Step>
</Steps>

## Key scopes

Assign the most restrictive scope that your integration requires.

| Scope        | Permissions                                                                                          |
| ------------ | ---------------------------------------------------------------------------------------------------- |
| `read-only`  | Read forms, submissions, workflows, and webhooks. Cannot create, modify, or delete anything.         |
| `read-write` | Full access to create, read, update, and delete all resources.                                       |
| `admin`      | All `read-write` permissions plus account management (inviting members, modifying billing settings). |

<Warning>
  Treat your API key like a password. Never commit it to version control, embed it in client-side code, or share it in plain text. Use environment variables or a secrets manager to store keys in production.
</Warning>

## Making authenticated requests

Pass your key in the `Authorization` header with every request.

<CodeGroup>
  ```bash curl theme={null}
  curl --request GET \
    --url "https://api.formflows.ai/v1/forms" \
    --header "Authorization: Bearer sk_live_your_api_key" \
    --header "Content-Type: application/json"
  ```

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

  API_KEY = "sk_live_your_api_key"  # Load from environment in production

  response = requests.get(
      "https://api.formflows.ai/v1/forms",
      headers={
          "Authorization": f"Bearer {API_KEY}",
          "Content-Type": "application/json",
      },
  )

  data = response.json()
  ```

  ```javascript JavaScript theme={null}
  const API_KEY = process.env.FORMFLOWS_API_KEY;

  const response = await fetch("https://api.formflows.ai/v1/forms", {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
  });

  const data = await response.json();
  ```
</CodeGroup>

## Rotating and revoking keys

To rotate a key:

1. Create a new key with the same scope.
2. Update your application to use the new key.
3. Delete the old key from the **API Keys** settings page.

To revoke a key immediately, click the trash icon next to it in **Settings → API Keys**. Requests using a revoked key are rejected immediately.

<Tip>
  Set a calendar reminder to rotate your API keys periodically. For high-security environments, rotate every 90 days.
</Tip>

## Authentication errors

If your key is missing or invalid, the API returns a `401` response:

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "No valid API key provided.",
    "status": 401
  }
}
```

If your key is valid but lacks permission for the requested action, you'll receive a `403`:

```json theme={null}
{
  "error": {
    "code": "forbidden",
    "message": "Your API key does not have permission to perform this action.",
    "status": 403
  }
}
```