secure-flows

Returns the decrypted session payload for the authenticated internal session token. Response shape is a **flat JSON object**. Empty payload returns `{}`. Source: GET /api/v1/sessions Requires `auth.sessionToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "sessionToken": {
          "type": "string",
          "description": "secureFlows session token"
        }
      },
      "required": [
        "sessionToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {}
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {}
  },
  "required": [
    "connection"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Verifies **Firebase** ID token, creates a session for **`workspaceName`**, stores serialized **`payload`** (defaults to `{}` when omitted), and returns **`sessionToken`** (JWT; subject = internal session id). Default server-side TTL is **1 hour** (implementation detail). If the Firebase token includes **`email`**, the server best-effort persists it on the workspace end-user row (for audit display). Prefer **`POST /sessions/get-or-create`** for hosted-login-style flows that should reuse an active session. Source: POST /api/v1/sessions Requires `auth.firebaseToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "firebaseToken": {
          "type": "string",
          "description": "Firebase ID token"
        }
      },
      "required": [
        "firebaseToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {}
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {
      "type": "object",
      "properties": {
        "workspaceName": {
          "type": "string",
          "description": "Workspace name to scope the session"
        },
        "app_id": {
          "anyOf": [
            {
              "type": "string",
              "description": "Optional app id (must belong to the workspace). Used for per-app session policy and auditing."
            },
            {
              "type": "null"
            }
          ]
        },
        "payload": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {},
          "description": "Arbitrary payload object stored in the session. Optional; omitted or null is stored as `{}`."
        }
      },
      "required": [
        "workspaceName"
      ]
    }
  },
  "required": [
    "connection",
    "body"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns the workspace end-user's **`userId`** and **email** for the authenticated session token. Does not return Firebase UID or session payload. `userId` is a stable, opaque identifier for this person across sessions and logins — it is **not** derived from Firebase. Use it as the correlation key when your own backend needs to link an external event (e.g. a billing provider webhook you receive and verify yourself) back to this user. Do not use the session token or session id for this — sessions expire and rotate, `userId` does not. Email is best-effort from hosted login (Firebase `email` claim persisted on the user row). When unknown, `email` is `null`. Browser SDK: **`secureflows-js`** **`fetchSessionIdentity(token)`** (≥ 0.1.15 for `userId`). Source: GET /api/v1/sessions/identity Requires `auth.sessionToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "sessionToken": {
          "type": "string",
          "description": "secureFlows session token"
        }
      },
      "required": [
        "sessionToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {}
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {}
  },
  "required": [
    "connection"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Verifies **Firebase** ID token. If an **active** session already exists for **`(workspaceName, Firebase UID, app_id)`**, returns a new **`sessionToken`** JWT for the **most recently created** matching row (touches activity; does not create a duplicate session). The request **`payload` is ignored on reuse** — it is applied only when a new session row is created. Prefer a dedicated `app_id` per integration surface, or revoke old sessions, if you need a fresh payload. Otherwise behaves like **`POST /sessions`** (new row + default **1 hour** TTL). If the Firebase token includes **`email`**, the server best-effort persists or backfills it on the workspace end-user row (including when reusing an existing session). Intended for integrators that mirror hosted login session reuse. Source: POST /api/v1/sessions/get-or-create Requires `auth.firebaseToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "firebaseToken": {
          "type": "string",
          "description": "Firebase ID token"
        }
      },
      "required": [
        "firebaseToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {}
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {
      "type": "object",
      "properties": {
        "workspaceName": {
          "type": "string",
          "description": "Workspace name to scope the session"
        },
        "app_id": {
          "anyOf": [
            {
              "type": "string",
              "description": "Optional app id (must belong to the workspace). Used for per-app session policy and auditing."
            },
            {
              "type": "null"
            }
          ]
        },
        "payload": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {},
          "description": "Arbitrary payload object stored in the session. Optional; omitted or null is stored as `{}`."
        }
      },
      "required": [
        "workspaceName"
      ]
    }
  },
  "required": [
    "connection",
    "body"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Verifies **Firebase** ID token. Parses **`sessionToken`** path segment as an internal SESSION JWT **without enforcing JWT expiry** (signature and `tokenType=SESSION` are still validated). Loads the session by id from the token subject; the Firebase UID must match the session owner. Increments **`tokenRevision`** on the server so **previous session JWTs** (same session id, older revision) are no longer accepted for `GET/POST/DELETE /sessions/...`. Returns a **new `sessionToken`** (with the new `tokenRevision` claim) and the current decrypted **payload**; extends server-side session expiry by **1 hour**. If the Firebase token includes **`email`**, the server best-effort backfills it on the session owner when the user row has no email yet (audit display only). Use the path form `POST /api/v1/sessions/renew/{sessionToken}` — **URL-encode** the JWT (e.g. `encodeURIComponent` in JS). Source: POST /api/v1/sessions/renew/{sessionToken} Requires `auth.firebaseToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "firebaseToken": {
          "type": "string",
          "description": "Firebase ID token"
        }
      },
      "required": [
        "firebaseToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {
        "sessionToken": {
          "type": "string",
          "description": "Previous SESSION JWT (may be expired); URL-encoded in the path"
        }
      },
      "required": [
        "sessionToken"
      ]
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {}
  },
  "required": [
    "connection",
    "params"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Sets a key in the encrypted session payload and returns the updated decrypted payload. If the JSON body is `{ "value": <x> }`, the server unwraps it and stores `<x>` directly. Source: POST /api/v1/sessions/set/{key} Requires `auth.sessionToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "sessionToken": {
          "type": "string",
          "description": "secureFlows session token"
        }
      },
      "required": [
        "sessionToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "Payload key to set"
        }
      },
      "required": [
        "key"
      ]
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "value": {}
          },
          "required": [
            "value"
          ]
        },
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "boolean"
        },
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        {}
      ],
      "description": "JSON body can be either `{ \"value\": <x> }` (preferred) or a raw JSON value.\n"
    }
  },
  "required": [
    "connection",
    "params",
    "body"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Retrieves the decrypted payload value for `key`. **Important:** `404` means the key was never written (normal first-use case). Do not treat as an error. Source: GET /api/v1/sessions/get/{key} Requires `auth.sessionToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "sessionToken": {
          "type": "string",
          "description": "secureFlows session token"
        }
      },
      "required": [
        "sessionToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "Payload key to read"
        }
      },
      "required": [
        "key"
      ]
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {}
  },
  "required": [
    "connection",
    "params"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Removes `key` from the session payload and returns `true` if the key existed. Source: DELETE /api/v1/sessions/delete/{key} Requires `auth.sessionToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "sessionToken": {
          "type": "string",
          "description": "secureFlows session token"
        }
      },
      "required": [
        "sessionToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "Payload key to delete"
        }
      },
      "required": [
        "key"
      ]
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {}
  },
  "required": [
    "connection",
    "params"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Revokes the session referenced by the internal SESSION Bearer token. This endpoint is useful for automation clients that only hold a session token and want to revoke it cleanly. Source: POST /api/v1/sessions/revoke Requires `auth.sessionToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "sessionToken": {
          "type": "string",
          "description": "secureFlows session token"
        }
      },
      "required": [
        "sessionToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {}
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {}
  },
  "required": [
    "connection"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

**Browser redirect endpoint** used after hosted `/app/sessions/login`. No `Authorization` header. 1. Verifies **`firebaseToken`** (Firebase ID token). 2. Ensures **`client_redirect_uri`** is allowlisted for **`app_id`** (same rules as `validate-redirect`). 3. **Create vs renew:** If **`session_token`** is absent, **reuses the newest active session** for **`(workspace_name, Firebase UID, app_id)`** or **creates** one (`get-or-create`). Optional **`payload`** (URL-encoded JSON **object**, default `{}`) is stored **only on create** — ignored when reusing an existing session. If **`session_token`** is present (previous session JWT, may be expired), **renews** that session; **`payload`** must **not** be sent on the same request. Optional **`ttl_seconds`** applies to both paths (default **0** = unlimited; otherwise **60–604800**). When the Firebase token includes **`email`**, the server best-effort persists or backfills it on the workspace end-user row (audit display only). 4. Responds with **`302 Found`** to `client_redirect_uri` with query params **`sessionToken`** and, if provided, **`state`**. If **`client_redirect_uri`** is not allowed for **`app_id`**, responds **`400`** and does **not** redirect (open-redirect mitigation). Other failures return an HTTP error status with a JSON **`{"status", "error"}`** body and do **not** redirect. Source: GET /api/v1/auth/callback No Authorization header is required. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {}
    },
    "params": {
      "type": "object",
      "properties": {}
    },
    "query": {
      "type": "object",
      "properties": {
        "firebaseToken": {
          "type": "string"
        },
        "client_redirect_uri": {
          "type": "string",
          "format": "uri"
        },
        "workspace_name": {
          "type": "string"
        },
        "app_id": {
          "type": "string"
        },
        "state": {
          "type": "string"
        },
        "ttl_seconds": {
          "description": "Session lifetime in seconds (default 0 = unlimited; allowed values: 0 or 60–604800)",
          "type": "integer",
          "minimum": 0,
          "maximum": 604800
        },
        "payload": {
          "description": "JSON object as a string (e.g. `{\"a\":1}`), URL-encoded. Must parse to a JSON object (not an array or primitive).\nDefault when omitted is `{}`. Must not be combined with `session_token` on the same request.\n",
          "type": "string"
        },
        "session_token": {
          "description": "Previous session JWT (may be expired); signature must validate. When present, the server renews this\nsession instead of creating a new one. Must not be combined with `payload` on the same request.\nURL-encode the value; very long URLs may exceed browser or proxy limits.\n",
          "type": "string"
        }
      },
      "required": [
        "firebaseToken",
        "client_redirect_uri",
        "workspace_name",
        "app_id"
      ]
    },
    "body": {}
  },
  "required": [
    "connection",
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Browser-friendly logout endpoint for **cross-site** clients (e.g. apps running on `localhost`). Use this as a **top-level navigation** (not XHR/fetch) so `Clear-Site-Data` is applied in a **first-party** context on `secure-flows.com`, making cookie/session clearing reliable even when third-party cookies are blocked. **Critical client rules:** - Clear your in-app `sessionToken` state **before** navigating. - **Never** include `session_token` inside `redirect_uri` (that would silently renew and defeat logout). This endpoint (best-effort / idempotent for browser UX): - Invalidates the provided `session_token` by incrementing `tokenRevision` when the token still matches an **active** session (no new token is issued). - If the session is already expired/revoked or the revision was superseded by renew, still completes logout UX (does **not** return 401 solely for that reason). - Revokes Firebase refresh tokens for the session’s stored Firebase UID when known. - Sets `Clear-Site-Data: "cookies"`. - Redirects the browser to `redirect_uri`. Source: GET /api/v1/auth/logout No Authorization header is required. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {}
    },
    "params": {
      "type": "object",
      "properties": {}
    },
    "query": {
      "type": "object",
      "properties": {
        "session_token": {
          "type": "string",
          "description": "SESSION JWT to invalidate (URL-encoded)"
        },
        "redirect_uri": {
          "type": "string",
          "format": "uri",
          "description": "Where to redirect after logout completes"
        }
      },
      "required": [
        "session_token",
        "redirect_uri"
      ]
    },
    "body": {}
  },
  "required": [
    "connection",
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Logs out the current session **without revoking** it. **Browser warning:** calling this endpoint via XHR/fetch from a different origin than `secure-flows.com` is not a reliable way to clear hosted-login cookies. For browser apps (especially localhost), prefer the redirect helper `GET /api/v1/auth/logout?session_token=...&redirect_uri=...`. Behavior: - **Invalidates** the current `sessionToken` by incrementing `tokenRevision` (no new token is issued). - Calls Firebase `revokeRefreshTokens(firebaseUid)` using the session’s stored Firebase UID. - Sets `Clear-Site-Data: "cookies"` to clear browser cookies (including Firebase session cookie). Session payload and session row are **not** deleted or modified (other than `tokenRevision`). Source: POST /api/v1/auth/logout Requires `auth.sessionToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "sessionToken": {
          "type": "string",
          "description": "secureFlows session token"
        }
      },
      "required": [
        "sessionToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {}
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {}
  },
  "required": [
    "connection"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns a page of sessions for the current user within the current workspace. Self-service dashboard endpoint — requires workspace **`enableSelfService: true`**. Payload is included only for rows whose computed status is active. Sort keys match the admin workspace session list; `pageSize` is clamped to 1–200 (default 20). Source: GET /api/v1/sessions/my Requires `auth.userToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "userToken": {
          "type": "string",
          "description": "secureFlows USER token"
        }
      },
      "required": [
        "userToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {}
    },
    "query": {
      "type": "object",
      "properties": {
        "page": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "pageSize": {
          "description": "Page size (server clamps to 1–200; 0 or invalid uses default 20).",
          "type": "integer",
          "minimum": 1,
          "maximum": 200
        },
        "q": {
          "description": "Search by session id, app id, or user identifier (own uid)",
          "type": "string"
        },
        "status": {
          "description": "Computed session lifecycle filter (`all` or same values as admin session list).",
          "type": "string",
          "enum": [
            "all",
            "active",
            "expired",
            "revoked"
          ]
        },
        "app_id": {
          "description": "Filter by client app id, or `all`.",
          "type": "string"
        },
        "sort": {
          "type": "string",
          "enum": [
            "id",
            "user",
            "app",
            "created",
            "expires",
            "status",
            "lastActivity",
            "updated"
          ]
        },
        "dir": {
          "type": "string",
          "enum": [
            "asc",
            "desc"
          ]
        }
      }
    },
    "body": {}
  },
  "required": [
    "connection",
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Self-service dashboard endpoint. Revokes a session owned by the caller in the current workspace. Requires workspace **`enableSelfService: true`**. Source: POST /api/v1/sessions/revoke/{sessionId} Requires `auth.userToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "userToken": {
          "type": "string",
          "description": "secureFlows USER token"
        }
      },
      "required": [
        "userToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {
        "sessionId": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "sessionId"
      ]
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {}
  },
  "required": [
    "connection",
    "params"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Embeds the query with Ollama (`nomic-embed-text`) and returns the closest public doc chunks from the environment's search index (pgvector). Source: GET /api/v1/docs/search No Authorization header is required. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {}
    },
    "params": {
      "type": "object",
      "properties": {}
    },
    "query": {
      "type": "object",
      "properties": {
        "q": {
          "type": "string",
          "description": "Natural-language question or keywords"
        },
        "limit": {
          "description": "Maximum hits to return (server caps at 20)",
          "type": "integer",
          "minimum": 1,
          "maximum": 20
        }
      },
      "required": [
        "q"
      ]
    },
    "body": {}
  },
  "required": [
    "connection",
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Builds a correct hosted-login redirect URL. Needs no secureFlows token — safe to call at app-scaffolding time, before any user session exists, which is the phase most secureFlows integration mistakes happen in. Always targets /app/sessions/login (session apps). Never builds the legacy /app/login console URL, which returns a firebaseToken your SecureFlowsCallback handler cannot consume and causes an infinite redirect loop. Use this instead of hand-building the URL with URLSearchParams — hand-built login URLs are the #1 source of the login-loop and stale-renewal bugs documented in SKILL.md.

{
  "type": "object",
  "properties": {
    "origin": {
      "default": "https://www.secure-flows.com",
      "description": "secureFlows origin — always https://www.secure-flows.com in production",
      "type": "string",
      "format": "uri"
    },
    "workspaceName": {
      "type": "string",
      "description": "Workspace name from the human prompt (\"workspace = ...\")"
    },
    "appId": {
      "type": "string",
      "description": "App id from the human prompt (\"appId = ...\")"
    },
    "redirectUri": {
      "type": "string",
      "format": "uri",
      "description": "The app's unguarded /callback URL, built from the published/allowlisted app origin — never from an iframe or editor chrome origin."
    },
    "intent": {
      "default": "fresh_login",
      "description": "fresh_login: normal sign-in, or app-load restore with no prior token (default — almost always correct, including after an explicit sign-out). renew_expired_token: ONLY when resuming the SAME still-intended user after a soft token expiry (401/410) while staying logged in — never after Sign out.",
      "type": "string",
      "enum": [
        "fresh_login",
        "renew_expired_token"
      ]
    },
    "expiredToken": {
      "description": "The old sessionToken to renew. Only read when intent=renew_expired_token. Setting this after an explicit sign-out is the \"send a dead JWT into hosted login\" anti-pattern — it breaks renewal when the underlying identity changed.",
      "type": "string"
    }
  },
  "required": [
    "workspaceName",
    "appId",
    "redirectUri"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Builds a correct redirect-logout URL and refuses to build one that violates the two documented logout anti-patterns: a redirect_uri pointing at /callback (SPA callback handlers treat the tokenless return as a failed login and loop), and a redirect_uri that itself embeds session_token (silently renews the old session instead of signing out). The result always instructs top-level navigation, never fetch/XHR — cross-site fetch() to this endpoint gets a 200 but browsers silently ignore its Clear-Site-Data header on cross-site responses, so the hosted-login cookie survives and the user silently re-authenticates on the next login redirect. This tool never builds a revoke request: revoke permanently destroys the user's data and must only run on an explicit "delete my account" action, never on ordinary sign-out.

{
  "type": "object",
  "properties": {
    "origin": {
      "default": "https://www.secure-flows.com",
      "description": "secureFlows origin — always https://www.secure-flows.com in production",
      "type": "string",
      "format": "uri"
    },
    "sessionToken": {
      "type": "string",
      "description": "The current sessionToken to invalidate."
    },
    "postLogoutRedirectUri": {
      "type": "string",
      "format": "uri",
      "description": "Where the browser lands after logout completes — allowlisted, must NOT be /callback, and must NOT itself contain session_token."
    }
  },
  "required": [
    "sessionToken",
    "postLogoutRedirectUri"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Checks source you already generated against the secureFlows integration rules. Needs no secureFlows token; safe at scaffolding time. Pass every auth/session-related file in one call — some checks are evaluated across the whole set. Two kinds of findings: • scope "file" — a forbidden construct is present (localStorage token, legacy /app/login, fetch-based logout, client-side JWT decode, empty catch, restore non-auth errors clearing session UI, Continue CTA gated on null session, ...), reported at an exact file:line. • scope "project" — REQUIRED handling is missing everywhere you passed in: detecting 401/410 but never clearing the token, never handling 403, or handling 403 without the BILLING_GRACE_LOCK carve-out. These are the defects that actually dominate real generated apps, and no "forbidden pattern" check can see them, because the bug is an absence. Heuristic text analysis, not a parser or a type checker. It can miss things it has no rule for, and a project check can be satisfied by the right keyword in the wrong place. It is a fast first pass — not a substitute for the Agent implementation checklist in SKILL.md, and specifically not for the checks that need a running app (auth-guard mount races, the fresh-reload check). Fix every "error" before calling an integration done; treat "needs_review" as a lead.

{
  "type": "object",
  "properties": {
    "files": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      },
      "description": "Map of relative file path -> full file source to scan, e.g. { \"src/lib/secureflows.js\": \"...\" }"
    }
  },
  "required": [
    "files"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}