Flow Management

Overview

The Flow Management API provides endpoints for defining and managing custom authentication flows. With graph-based flow definitions, you can flexibly build complex authentication scenarios.

Endpoint List

Method	Endpoint	Description
GET	/api/admin/flows	List flows
GET	/api/admin/flows/:id	Get flow details
POST	/api/admin/flows	Create flow
PUT	/api/admin/flows/:id	Update flow
DELETE	/api/admin/flows/:id	Delete flow
POST	/api/admin/flows/:id/validate	Validate flow
POST	/api/admin/flows/:id/compile	Compile flow
POST	/api/admin/flows/:id/activate	Activate flow
POST	/api/admin/flows/:id/deactivate	Deactivate flow

---

List Flows

Retrieve a list of flows within the tenant.

Endpoint

GET /api/admin/flows

Query Parameters

Parameter	Type	Required	Description
limit	integer	-	Number of items (default: 20, max: 100)
cursor	string	-	Pagination cursor
type	string	-	Filter by flow type
status	string	-	Filter by status (active, inactive, draft)

Request Example

curl -X GET "https://{tenant-domain}/api/admin/flows?type=login" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "id": "flow_login_default",
      "name": "default-login",
      "display_name": "Default Login Flow",
      "type": "login",
      "status": "active",
      "version": 3,
      "created_at": 1705881600,
      "updated_at": 1706054400
    },
    {
      "id": "flow_login_mfa",
      "name": "mfa-login",
      "display_name": "MFA Login Flow",
      "type": "login",
      "status": "active",
      "version": 1,
      "created_at": 1705968000,
      "updated_at": 1705968000
    }
  ],
  "total": 5,
  "cursor": null
}

---

Get Flow Details

Retrieve detailed information for a specified flow.

Endpoint

GET /api/admin/flows/:id

Path Parameters

Parameter	Type	Required	Description
id	string	✓	Flow ID

Request Example

curl -X GET "https://{tenant-domain}/api/admin/flows/flow_login_mfa" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "flow_login_mfa",
  "name": "mfa-login",
  "display_name": "MFA Login Flow",
  "description": "Flow with MFA verification after password authentication",
  "type": "login",
  "status": "active",
  "version": 1,
  "graph": {
    "nodes": [
      {
        "id": "start",
        "type": "start",
        "position": { "x": 0, "y": 0 }
      },
      {
        "id": "identifier",
        "type": "identifier_input",
        "config": {
          "identifier_types": ["email", "username"]
        },
        "position": { "x": 200, "y": 0 }
      },
      {
        "id": "password",
        "type": "password_input",
        "position": { "x": 400, "y": 0 }
      },
      {
        "id": "mfa_check",
        "type": "condition",
        "config": {
          "condition": "user.mfa_enabled"
        },
        "position": { "x": 600, "y": 0 }
      },
      {
        "id": "mfa_verify",
        "type": "mfa_verification",
        "config": {
          "methods": ["totp", "sms"]
        },
        "position": { "x": 800, "y": -100 }
      },
      {
        "id": "success",
        "type": "success",
        "position": { "x": 1000, "y": 0 }
      }
    ],
    "edges": [
      { "source": "start", "target": "identifier" },
      { "source": "identifier", "target": "password" },
      { "source": "password", "target": "mfa_check" },
      { "source": "mfa_check", "target": "mfa_verify", "condition": "true" },
      { "source": "mfa_check", "target": "success", "condition": "false" },
      { "source": "mfa_verify", "target": "success" }
    ]
  },
  "compiled": true,
  "compiled_at": 1705968000,
  "created_at": 1705968000,
  "updated_at": 1705968000
}

---

Create Flow

Create a new flow.

Endpoint

POST /api/admin/flows

Request Body

Field	Type	Required	Description
name	string	✓	Flow name (alphanumeric, hyphens)
display_name	string	✓	Display name
description	string	-	Description
type	string	✓	Flow type
graph	object	✓	Flow graph definition

Flow Types

Type	Description
login	Login flow
registration	User registration flow
password_reset	Password reset flow
mfa_setup	MFA setup flow
account_recovery	Account recovery flow

Request Example

curl -X POST "https://{tenant-domain}/api/admin/flows" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "social-login",
    "display_name": "Social Login Flow",
    "description": "Login using social providers",
    "type": "login",
    "graph": {
      "nodes": [
        { "id": "start", "type": "start" },
        { "id": "provider_select", "type": "social_provider_select", "config": { "providers": ["google", "github"] } },
        { "id": "success", "type": "success" }
      ],
      "edges": [
        { "source": "start", "target": "provider_select" },
        { "source": "provider_select", "target": "success" }
      ]
    }
  }'

Response Example

{
  "id": "flow_social_login",
  "name": "social-login",
  "display_name": "Social Login Flow",
  "type": "login",
  "status": "draft",
  "version": 1,
  "compiled": false,
  "created_at": 1706140800
}

---

Update Flow

Update an existing flow.

Endpoint

PUT /api/admin/flows/:id

Request Example

curl -X PUT "https://{tenant-domain}/api/admin/flows/flow_social_login" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Social Login Flow (Updated)",
    "graph": {
      "nodes": [
        { "id": "start", "type": "start" },
        { "id": "provider_select", "type": "social_provider_select", "config": { "providers": ["google", "github", "apple"] } },
        { "id": "success", "type": "success" }
      ],
      "edges": [
        { "source": "start", "target": "provider_select" },
        { "source": "provider_select", "target": "success" }
      ]
    }
  }'

---

Delete Flow

Delete a flow.

Endpoint

DELETE /api/admin/flows/:id

Request Example

curl -X DELETE "https://{tenant-domain}/api/admin/flows/flow_social_login" \
  -H "Authorization: Bearer {token}"

Deletion Constraint

Flows with active status cannot be deleted. Deactivate them first.

---

Validate Flow

Validate that the flow definition is correct.

Endpoint

POST /api/admin/flows/:id/validate

Request Example

curl -X POST "https://{tenant-domain}/api/admin/flows/flow_social_login/validate" \
  -H "Authorization: Bearer {token}"

Response Example (Success)

{
  "valid": true,
  "warnings": [
    {
      "code": "unused_node",
      "message": "Node 'fallback' is unreachable",
      "node_id": "fallback"
    }
  ]
}

Response Example (Error)

{
  "valid": false,
  "errors": [
    {
      "code": "missing_start_node",
      "message": "Flow is missing a start node"
    },
    {
      "code": "unreachable_success",
      "message": "No path to success node"
    },
    {
      "code": "invalid_edge",
      "message": "Edge 'password->mfa' target node does not exist",
      "edge": { "source": "password", "target": "mfa" }
    }
  ]
}

---

Compile Flow

Compile the flow into an executable format.

Endpoint

POST /api/admin/flows/:id/compile

Request Example

curl -X POST "https://{tenant-domain}/api/admin/flows/flow_social_login/compile" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "flow_social_login",
  "compiled": true,
  "compiled_at": 1706227200,
  "version": 2
}

---

Activate Flow

Activate a flow.

Endpoint

POST /api/admin/flows/:id/activate

Request Example

curl -X POST "https://{tenant-domain}/api/admin/flows/flow_social_login/activate" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "flow_social_login",
  "status": "active",
  "activated_at": 1706313600
}

---

Deactivate Flow

Deactivate a flow.

Endpoint

POST /api/admin/flows/:id/deactivate

Request Example

curl -X POST "https://{tenant-domain}/api/admin/flows/flow_social_login/deactivate" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "flow_social_login",
  "status": "inactive",
  "deactivated_at": 1706400000
}

---

Node Types

Input Nodes

Type	Description
identifier_input	User identifier input (email, username, etc.)
password_input	Password input
social_provider_select	Social provider selection
mfa_verification	MFA verification
otp_input	One-time password input

Control Nodes

Type	Description
start	Flow start
success	Flow success end
failure	Flow failure end
condition	Conditional branch
switch	Multiple branch

Action Nodes

Type	Description
send_email	Send email
send_sms	Send SMS
webhook	Webhook call
set_attribute	Set attribute