API Tokens¶

Overview¶

Dev/Test Only: floh_* API tokens are only accepted in development and test environments (NODE_ENV=development or NODE_ENV=test). Production environments require OIDC access tokens from Authifi. See MCP Setup for production configuration.

API tokens allow users to delegate a scoped subset of their permissions to external tools (AI assistants, CI/CD pipelines, scripts). Tokens are:

Scoped to a subset of the creating user's permissions
Time-limited (max 1 year)
Instantly revocable
Fully auditable (every action records the token identity)
Dev/test only — rejected in production environments

Creating a Token¶

Use the API to create a token:

curl -X POST https://floh.example.com/api/auth/tokens \
  -H "Authorization: Bearer <your-session-or-idp-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cursor MCP",
    "permissions": ["workflow:read", "workflow:create", "workflow:update", "workflow:publish", "run:read", "project:read", "connector:read"],
    "expiresInDays": 90
  }'

Response includes the raw token (shown once only):

{
  "id": "uuid",
  "token": "floh_a1b2c3d4e5f6...",
  "name": "Cursor MCP",
  "prefix": "floh_a1b2c3d4",
  "permissions": [...],
  "expiresAt": "2026-06-08T..."
}

You can also create tokens via the Floh web UI under your profile settings.

Using a Token¶

Include the token in API calls via the Authorization header:

curl -H "Authorization: Bearer floh_a1b2c3d4..." https://floh.example.com/api/workflows

Permission Scoping¶

Tokens can only include permissions the user currently has
Effective permissions = intersection of (token grants) AND (user's current role-based permissions)
If the user's role is later downgraded, the token's effective permissions shrink automatically
Example: token has [A,B,C], user later only has [B,C,D] → effective is [B,C]

Token Profiles¶

Suggested permission sets for common use cases:

Profile	Permissions	Use Case
Read-only analyst	`workflow:read`, `run:read`, `task:read`, `approval:read`, `project:read`, `connector:read`, `audit:read`, `report:read`	Monitoring, reporting, failure analysis
Workflow author	Read-only + `workflow:create`, `workflow:update`, `workflow:publish`, `workflow:start`, `schedule:read`, `schedule:manage`	AI-assisted workflow development
Full operator	Author + `run:cancel`, `run:update`, `config:export`, `config:import`	Full CI/CD automation

Listing Tokens¶

GET /api/auth/tokens — returns your tokens (never returns the raw token value)

Revoking Tokens¶

DELETE /api/auth/tokens/:id — revokes a token immediately

Security Notes¶

Store tokens securely (environment variables, secret managers)
Use the shortest expiry that's practical
Create separate tokens for different tools
Revoke tokens when no longer needed
All token-based actions are recorded in the audit log with via: "api_token" metadata

Required Permissions¶

To create, list, and revoke tokens, you need: token:create, token:read, token:revoke (granted to admin and resource_manager roles)