Skip to main content

​
What are external users?

External users are the end users of your app or product — the people you identify inside Flowra (by a username or ID) so you can scope actions to them. For example: in a multi-tenant app, each of your customers might be an “external user”; when they connect Slack or run a workflow, you pass their identity so Flowra can use their connected accounts or store results under their user. The API lets you list all external users for the project and get one by username, so you can look up “which Flowra user is this customer?” before calling workflows or other endpoints. So: you (the developer) use the API with an API key; external users are the identities you create for your own end users so Flowra can act on their behalf (e.g. their OAuth connections, their workflow runs).

​
Example use cases

  • Multi-tenant app — Each of your customers is an external user (username = email or your internal ID). When they connect Slack, the connected account is linked to that external user. When you run a workflow for them, you pass their context so the right Slack workspace is used.
  • User lookup — Before running a workflow or assigning a resource, call “get by username” to resolve your app’s user to a Flowra external user ID (if needed by other APIs).
  • Audit / admin — List all external users in the project to see who exists or to sync with your own user directory.

​
How it works

  • List — GET /external-users returns all external users for the project (id, name, projectId).
  • Get by username — GET /external-users/username/{username} returns one user by their username (name). Use this when you know the username and need the Flowra user id or to check they exist.
  • x-username header — On endpoints that support it, you can send x-username so the request runs in that external user’s context (e.g. connected accounts, per-user workflow state). Same username you use in the external-users API.
Base URL: Use the API base URL from your dashboard or deployment. Example URLs in the docs use https://flowra.dev/api/v1; your environment may use a different host or path. Not every endpoint may be enabled in every environment — if you get 404, check your project’s API base URL and that the feature is available for your plan or deployment.

​
API endpoints

​
Optional: x-username header

You can send x-username in the request header to act in the context of that external user on endpoints that support it (e.g. connected accounts, workflows that use per-user context). Use the same username (name) you use in the external-users API. This header is optional. For GET /api/v1/external-users (list), the response is the same with or without x-username — you get all external users for the project; x-username matters on other endpoints that run in a specific user’s context.

​
List external users

GET /api/v1/external-users returns all external users for the current project. Response includes id, name, and projectId for each user. 
curl -X GET "https://flowra.dev/api/v1/external-users" \
  -H "x-api-key: YOUR_API_KEY"

​
Get by username

GET /api/v1/external-users/username/{username} returns one external user by their username (name) within your project. Returns null if not found. Use to look up a user before assigning them to workflows or resources.