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

# Authentication

> How to authenticate with the SuperAI Flows API using JWT bearer tokens or service-account API keys.

SuperAI Flows uses **JWT-based authentication**, managed through `core.flows.super.ai`. All API endpoints except a small set of public paths require a valid bearer token. Some endpoints (and the MCP server) additionally accept a **service-account API key**.

## Authentication methods

| Method                 | Header                          | Best for                                 |
| ---------------------- | ------------------------------- | ---------------------------------------- |
| **Bearer token** (JWT) | `Authorization: Bearer <token>` | User-driven API access                   |
| **API key**            | `X-API-Key: saf_org_...`        | Programmatic / service-to-service access |

## Bearer token flow

<Steps>
  <Step title="Get your anonymous key">
    A public endpoint — no authentication required. The anon key is a long-lived key used only to authenticate against the auth service.

    ```bash theme={null}
    curl https://flows.super.ai/api/auth/anon-key
    ```
  </Step>

  <Step title="Authenticate to receive tokens">
    ```bash theme={null}
    curl -X POST 'https://core.flows.super.ai/auth/v1/token?grant_type=password' \
      -H 'Content-Type: application/json' \
      -H 'apikey: YOUR_ANON_KEY' \
      -d '{"email": "you@example.com", "password": "your-password"}'
    ```

    Returns a JWT `access_token` and a `refresh_token`.
  </Step>

  <Step title="Call the API with your access token">
    ```bash theme={null}
    curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
      https://flows.super.ai/api/flows
    ```
  </Step>
</Steps>

## Token lifetimes

| Token             | Lifetime | Use                                                |
| ----------------- | -------- | -------------------------------------------------- |
| **Access token**  | 1 hour   | Include in every API request                       |
| **Refresh token** | 30 days  | Obtain new access tokens without re-authenticating |

Refresh an expired access token:

```bash theme={null}
curl -X POST 'https://core.flows.super.ai/auth/v1/token?grant_type=refresh_token' \
  -H 'Content-Type: application/json' \
  -H 'apikey: YOUR_ANON_KEY' \
  -d '{"refresh_token": "YOUR_REFRESH_TOKEN"}'
```

## API keys

Service-account API keys (prefix `saf_`) provide programmatic access without a login flow. Create one under **Settings → Service Accounts** in the dashboard, then pass it via the `X-API-Key` header:

```bash theme={null}
curl -H "X-API-Key: saf_org_..." \
  https://flows.super.ai/api/flows
```

API keys are the only supported method for the [MCP server](/api-reference/mcp-server).

<Warning>
  Tokens and API keys grant access to your organization's resources — treat them like passwords. Store them in environment variables or a secret manager, use HTTPS for all requests, and never commit them to version control.
</Warning>

## Common authentication errors

| Status | Code                  | Meaning                                                     |
| ------ | --------------------- | ----------------------------------------------------------- |
| 401    | `user_info_not_found` | Token invalid, expired, or user not found — re-authenticate |
| 401    | —                     | Missing or malformed `Authorization` / `X-API-Key` header   |
| 403    | `forbidden`           | Authenticated, but no access to the requested resource      |

See the full [Error Codes reference](/api-reference/errors) for details.