## SuperAI Flows Authentication

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

1. **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
   curl https://flows.super.ai/api/auth/anon-key
   ```

2. **Authenticate to receive tokens**  
   
   ```bash
   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`.

3. **Call the API with your access token**  
   
   ```bash
   curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     https://flows.super.ai/api/flows
   ```

## 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
   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
   curl -H "X-API-Key: saf_org_..." \
     https://flows.super.ai/api/flows
   ```

API keys are the only supported method for the [MCP server](https://docs.flows.super.ai/api-reference/mcp-server).

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.

## 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](https://docs.flows.super.ai/api-reference/errors) for details.