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

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.

curl https://flows.super.ai/api/auth/anon-key

Authenticate to receive tokens

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.

Call the API with your access token

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:

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:

curl -H "X-API-Key: saf_org_..." \
  https://flows.super.ai/api/flows

API keys are the only supported method for the 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 for details.

Overview

Endpoints

Authentication methods

Bearer token flow

Token lifetimes

API keys

Common authentication errors

​Authentication methods

​Bearer token flow

​Token lifetimes

​API keys

​Common authentication errors

Authentication methods

Bearer token flow

Token lifetimes

API keys

Common authentication errors