Skip to content
flow8

API Authentication

API Authentication

Session Authentication

For browser-based clients. Login returns a session cookie valid for 1 hour.

Terminal window
# Login
curl -c cookies.txt -X POST http://localhost:4454/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"yourpassword"}'


# Response
{"id":"65user1","email":"user@example.com","name":"John Smith"}


# Use cookie in subsequent requests
curl -b cookies.txt http://localhost:4454/api/flows


# Logout
curl -b cookies.txt -X POST http://localhost:4454/api/auth/logout

API Key Authentication

For programmatic/server-to-server access. API keys are JWT tokens that do not expire by default.

Create an API key:

Terminal window
curl -b cookies.txt -X POST http://localhost:4454/api/auth/api-keys \
  -H "Content-Type: application/json" \
  -d '{"name":"CI Pipeline Key","scopes":["standard"]}'


# Response
{
  "id": "65key1",
  "name": "CI Pipeline Key",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scopes": ["standard"],
  "issuedAt": "2024-01-15T10:00:00Z"
}

Use the token:

Terminal window
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  http://localhost:4454/api/flows

JWT Structure:

{
  "userId": "65user1",
  "companyId": "65company1",
  "keyId": "65key1",
  "scopes": ["standard"],
  "iat": 1705312800
}

Scopes:

  • standard — full API access (all endpoints)
  • mcp — MCP server access only (for AI agents)

List and revoke keys:

Terminal window
# List
curl -b cookies.txt http://localhost:4454/api/auth/api-keys


# Revoke
curl -b cookies.txt -X DELETE http://localhost:4454/api/auth/api-keys/65key1

Best practices:

  • Create separate keys per integration (easier to rotate individually)
  • Use mcp scope for AI agents to limit blast radius
  • Store tokens in secrets management (not in code or .env files committed to git)
  • Revoke and reissue keys on team member departure