FlowOS Docs
Platform

Authentication & Security

API keys, OAuth 2.0, SSO with SAML/OIDC, RBAC, secrets vault, and audit controls.

Authentication Methods

FlowOS supports three ways to authenticate API requests:

  • •Bearer tokens — Long-lived API keys generated from the UI or token endpoint. Best for server-to-server integrations.
  • •OAuth 2.0 — Short-lived access tokens with refresh tokens. Best for user-facing applications.
  • •Session cookies — Browser-based sessions set after SSO or password login. Used by the FlowOS UI only.

API Keys

GET
/api/v1/auth/tokens

List all API tokens for the current user

POST
/api/v1/auth/tokens

Create a new API token

DELETE
/api/v1/auth/tokens/:id

Revoke an API token immediately

POST
/api/v1/auth/tokens/rotate

Issue a new token and revoke the old one atomically

Create a scoped token

bash
POST /api/v1/auth/tokens
{
  "name": "GitHub Actions — deploy pipeline",
  "expiresIn": "365d",           // or "30d", "90d", null for non-expiring
  "scopes": [
    "workflows:read",
    "workflows:trigger",
    "deployments:create",
    "apps:deploy"
  ],
  "ipAllowlist": ["203.0.113.0/24"]   // optional — restrict by IP CIDR
}

// Response
{
  "data": {
    "id": "tok_01HZ...",
    "name": "GitHub Actions — deploy pipeline",
    "token": "fos_live_4k2Xm9...",   // only shown ONCE — store immediately
    "scopes": ["workflows:read", "workflows:trigger", "deployments:create", "apps:deploy"],
    "expiresAt": "2027-06-01T00:00:00Z",
    "createdAt": "2026-06-01T00:00:00Z"
  }
}
The token value is shown only once at creation time. Store it securely in your CI/CD secrets or environment variables. If you lose it, rotate the token — the old one will be revoked immediately.

OAuth 2.0

Use OAuth 2.0 when building applications that act on behalf of FlowOS users. FlowOS implements the Authorization Code with PKCE flow.

Step 1 — Register your application

bash
POST /api/v1/oauth/applications
{
  "name": "Acme Mobile App",
  "redirectUris": ["https://mobile.acme.com/auth/callback"],
  "allowedScopes": ["incidents:read", "incidents:write", "profile"]
}

// Response
{
  "data": {
    "clientId": "oauth_client_01HZ...",
    "clientSecret": "oauth_sec_...",   // store securely, shown once
    "redirectUris": ["https://mobile.acme.com/auth/callback"]
  }
}

Step 2 — Redirect to authorization endpoint

bash
GET https://acme.flowos.io/oauth/authorize
  ?response_type=code
  &client_id=oauth_client_01HZ...
  &redirect_uri=https://mobile.acme.com/auth/callback
  &scope=incidents:read+incidents:write+profile
  &state=random-csrf-token
  &code_challenge=BASE64URL(SHA256(code_verifier))
  &code_challenge_method=S256

Step 3 — Exchange code for tokens

bash
POST /api/v1/oauth/token
{
  "grant_type": "authorization_code",
  "code": "auth_code_from_redirect",
  "redirect_uri": "https://mobile.acme.com/auth/callback",
  "client_id": "oauth_client_01HZ...",
  "code_verifier": "original-code-verifier"
}

// Response
{
  "access_token": "fos_access_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "fos_refresh_...",
  "scope": "incidents:read incidents:write profile"
}

Refresh an access token

bash
POST /api/v1/oauth/token
{
  "grant_type": "refresh_token",
  "refresh_token": "fos_refresh_...",
  "client_id": "oauth_client_01HZ..."
}

Single Sign-On (SSO)

FlowOS supports SSO via SAML 2.0 and OIDC (OpenID Connect). SSO is configured at workspace level. Once SSO is configured, users are redirected to your identity provider on login.

Configure SAML 2.0

bash
POST /api/v1/settings/sso
{
  "protocol": "saml2",
  "entityId": "https://acme.flowos.io/sso/saml/metadata",
  "ssoUrl": "https://acme.okta.com/app/flowos/sso/saml",
  "certificate": "MIIC...base64...cert==",
  "attributeMapping": {
    "email":     "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "firstName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
    "lastName":  "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
    "role":      "https://acme.com/claims/flowos_role"
  },
  "jitProvisioning": true,          // auto-create users on first SSO login
  "defaultRole": "operator",
  "enforceSSO": false               // true = disable password login for all users
}

Configure OIDC

bash
POST /api/v1/settings/sso
{
  "protocol": "oidc",
  "issuer": "https://accounts.google.com",
  "clientId": "1234567890-abc.apps.googleusercontent.com",
  "clientSecret": "GOCSPX-...",
  "scopes": ["openid", "email", "profile"],
  "claimsMapping": {
    "email": "email",
    "name":  "name"
  },
  "jitProvisioning": true,
  "defaultRole": "developer"
}

MFA

FlowOS supports TOTP (Google Authenticator, Authy) and WebAuthn (hardware keys, Touch ID, Face ID) as second factors.

GET
/api/v1/auth/mfa/status

Get MFA enrollment status for current user

POST
/api/v1/auth/mfa/totp/enroll

Begin TOTP enrollment — returns QR code URI

POST
/api/v1/auth/mfa/totp/verify

Verify TOTP code to complete enrollment

POST
/api/v1/auth/mfa/webauthn/register

Register a WebAuthn credential

POST
/api/v1/settings/security/enforce-mfa

Require MFA for all workspace users (admin only)

Secrets Vault

The FlowOS vault stores secrets (API keys, passwords, connection strings) encrypted at rest. Secrets are referenced in workflow node config as {{secrets.MY_SECRET}} — they are never logged or returned in API responses.

GET
/api/v1/secrets

List secret names (values never returned)

POST
/api/v1/secrets

Store a new secret

PUT
/api/v1/secrets/:name

Update (rotate) a secret value

DELETE
/api/v1/secrets/:name

Delete a secret

bash
POST /api/v1/secrets
{
  "name": "PAGERDUTY_KEY",
  "value": "pd_live_...",
  "description": "PagerDuty Events API v2 key"
}

// Secrets are referenced in workflow nodes as:
// "apiKey": "{{secrets.PAGERDUTY_KEY}}"
Rotate secrets using PUT /api/v1/secrets/:name. The new value takes effect immediately for all workflows and artifacts that reference it — no redeployment needed.

RBAC — Roles & Permissions

GET
/api/v1/settings/roles

List all roles (built-in and custom)

POST
/api/v1/settings/roles

Create a custom role

GET
/api/v1/settings/roles/:id

Get role with permission list

PATCH
/api/v1/settings/roles/:id

Update role permissions

bash
POST /api/v1/settings/roles
{
  "name": "ITSM Analyst",
  "description": "Can view and manage ITSM records; cannot access studios",
  "permissions": [
    "incidents:read",
    "incidents:write",
    "incidents:resolve",
    "changes:read",
    "problems:read",
    "knowledge:read",
    "knowledge:write",
    "cmdb:read"
  ]
}

Assign a role to a user

bash
POST /api/v1/settings/users/:userId/roles
{
  "roleId": "rol_itsm_analyst",
  "workspaceId": "ws_acme"   // optional for multi-workspace accounts
}