Skip to main content
FlownallyAPI Docs

Users

LLM
View as Markdown
Open llms.txt

Manage the people working in your Flownally workspace.

7 generated endpoints in this resource group.

get/users

Get users#

Returns people who can work in the current Flownally workspace.

Authorization

Scheme

  • bearerAuth

Required scopes

  • user:list

Allowed roles

  • owner
  • admin
  • agent

List workspace users.

Responses

  • Name
    200
    Type
    application/json
    Description
    List of users
  • Name
    default
    Type
    application/json
    Description
    Error

Related schemas

Request

GETRequest
curl -X GET "https://api.flownally.com/v1/users" \
  -H "Authorization: Bearer {token}"

Response

200application/json
{
  "users": [
    {
      "id": "usr_01HV8Y3K2R6G7K3F5B9N8M1Q0",
      "name": "Lina Nowak",
      "email": "lina@example.com",
      "teamIds": [
        "team_01HV8Y6W0W4T5A8S9V7Q2P1M3"
      ],
      "role": "admin",
      "joinedAt": "2026-04-30T08:30:00Z",
      "avatarUrl": "https://app.flownally.com/avatar/lina.png",
      "provider": "google",
      "emailVerified": true,
      "disabled": false
    }
  ]
}
get/users/me

Get current user profile#

Returns the authenticated user's profile.

Authorization

Scheme

  • bearerAuth

Required scopes

  • user:read_self

Allowed roles

  • owner
  • admin
  • agent

Read the caller's user record.

Responses

  • Name
    200
    Type
    application/json
    Description
    Current user profile
  • Name
    default
    Type
    application/json
    Description
    Error

Related schemas

Request

GETRequest
curl -X GET "https://api.flownally.com/v1/users/me" \
  -H "Authorization: Bearer {token}"

Response

200application/json
{
  "id": "usr_01HV8Y3K2R6G7K3F5B9N8M1Q0",
  "name": "Lina Nowak",
  "email": "lina@example.com",
  "teamIds": [
    "team_01HV8Y6W0W4T5A8S9V7Q2P1M3"
  ],
  "role": "admin",
  "joinedAt": "2026-04-30T08:30:00Z",
  "avatarUrl": "https://app.flownally.com/avatar/lina.png",
  "provider": "google",
  "emailVerified": true,
  "disabled": false
}
patch/users/me

Update current user profile#

Updates the authenticated user's name or avatar URL.

Authorization

Scheme

  • bearerAuth

Required scopes

  • user:update_self

Allowed roles

  • owner
  • admin
  • agent

Update the caller's user profile.

Request body

Send a application/json body. The body is required for this operation.

Optional attributes

  • Name
    name
    Type
    string
    Description
    Optional request attribute.
  • Name
    avatarUrl
    Type
    string
    Description
    Optional request attribute.

Responses

  • Name
    200
    Type
    application/json
    Description
    Updated user profile
  • Name
    default
    Type
    application/json
    Description
    Error

Related schemas

Request

PATCHRequest
curl -X PATCH "https://api.flownally.com/v1/users/me" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Lina Nowak",
  "avatarUrl": "https://app.flownally.com/avatar/lina.png"
}'

Response

200application/json
{
  "id": "usr_01HV8Y3K2R6G7K3F5B9N8M1Q0",
  "name": "Lina Nowak",
  "email": "lina@example.com",
  "teamIds": [
    "team_01HV8Y6W0W4T5A8S9V7Q2P1M3"
  ],
  "role": "admin",
  "joinedAt": "2026-04-30T08:30:00Z",
  "avatarUrl": "https://app.flownally.com/avatar/lina.png",
  "provider": "google",
  "emailVerified": true,
  "disabled": false
}
get/users/me/unread-count

Get current user's global unread message count#

Returns the total number of unread messages across all sessions for the authenticated user. This is the authoritative value used to hydrate the inbox badge on page load and on WebSocket reconnect; WebSocket deltas update the badge between requests.

Authorization

Scheme

  • bearerAuth

Required scopes

  • user:read_self

Allowed roles

  • owner
  • admin
  • agent

Read the caller's unread conversation count.

Responses

  • Name
    200
    Type
    application/json
    Description
    Global unread count
  • Name
    default
    Type
    application/json
    Description
    Error

Related schemas

Request

GETRequest
curl -X GET "https://api.flownally.com/v1/users/me/unread-count" \
  -H "Authorization: Bearer {token}"

Response

200application/json
{
  "count": 0
}
get/users/me/unread-summary

Authoritative unread summary with monotonic version#

Returns the unread messages count for the authenticated user plus a monotonically-increasing `version`. Clients use `version` to discard stale WebSocket `unread_count_update` / `conversation_read` events. Called by the web client on WebSocket (re)connect to bootstrap the unread badge.

Authorization

Scheme

  • bearerAuth

Required scopes

  • user:read_self

Allowed roles

  • owner
  • admin
  • agent

Read the caller's unread conversation summary.

Responses

  • Name
    200
    Type
    application/json
    Description
    Unread summary
  • Name
    default
    Type
    application/json
    Description
    Error

Related schemas

Request

GETRequest
curl -X GET "https://api.flownally.com/v1/users/me/unread-summary" \
  -H "Authorization: Bearer {token}"

Response

200application/json
{
  "count": 0,
  "conversations": 0,
  "version": 0
}
get/users/{userId}

Get user#

Returns one workspace member, including role and team membership.

Authorization

Scheme

  • bearerAuth

Required scopes

  • user:read

Allowed roles

  • owner
  • admin
  • agent

Read a workspace user.

Required parameters

  • Name
    userId
    Type
    path string
    Description
    Required parameter.

Responses

  • Name
    200
    Type
    application/json
    Description
    User
  • Name
    404
    Type
    application/json
    Description
    User not found
  • Name
    default
    Type
    application/json
    Description
    Error

Related schemas

Request

GETRequest
curl -X GET "https://api.flownally.com/v1/users/{userId}" \
  -H "Authorization: Bearer {token}"

Response

200application/json
{
  "id": "usr_01HV8Y3K2R6G7K3F5B9N8M1Q0",
  "name": "Lina Nowak",
  "email": "lina@example.com",
  "teamIds": [
    "team_01HV8Y6W0W4T5A8S9V7Q2P1M3"
  ],
  "role": "admin",
  "joinedAt": "2026-04-30T08:30:00Z",
  "avatarUrl": "https://app.flownally.com/avatar/lina.png",
  "provider": "google",
  "emailVerified": true,
  "disabled": false
}
put/users/{userId}/role

Update a member's role#

Changes the role of a tenant member. The caller must hold a role with authority over the requested role transition. Admins can shuffle members between admin and agent; only Owners can mint or demote Owners. A tenant must retain at least one Owner — demoting the last one is rejected.

Authorization

Scheme

  • bearerAuth

Required scopes

  • user:assign_role_admin
  • user:assign_role_agent
  • user:assign_role_owner

Allowed roles

  • owner
  • admin

Assign a user role; required action depends on request body role.

Required parameters

  • Name
    userId
    Type
    path string
    Description
    Required parameter.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

  • Name
    role
    Type
    enum
    Description
    The role to assign to the member.Allowed: owner, admin, agent

Responses

  • Name
    200
    Type
    application/json
    Description
    Member updated
  • Name
    400
    Type
    application/json
    Description
    Invalid request. Codes: - `auth_user_invalid_role` — role is not one of owner/admin/agent - `auth_user_self_role_change_forbidden` — caller targeted themselves
  • Name
    403
    Type
    application/json
    Description
    Caller lacks authority for this role change. Codes: - `auth_authz_user_assign_role_denied` — matrix rejects the new role (e.g. Admin attempting Owner) - `auth_user_role_assignment_forbidden` — caller cannot edit an Owner target
  • Name
    404
    Type
    application/json
    Description
    Target user not found in the caller's tenant. Code: - `auth_user_not_found`
  • Name
    409
    Type
    application/json
    Description
    Tenant invariant would be violated. Code: - `auth_user_last_owner_required` — demotion would leave zero Owners
  • Name
    default
    Type
    application/json
    Description
    Error

Related schemas

Request

PUTRequest
curl -X PUT "https://api.flownally.com/v1/users/{userId}/role" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "agent"
}'

Response

200application/json
{
  "id": "usr_01HV8Y3K2R6G7K3F5B9N8M1Q0",
  "name": "Lina Nowak",
  "email": "lina@example.com",
  "teamIds": [
    "team_01HV8Y6W0W4T5A8S9V7Q2P1M3"
  ],
  "role": "admin",
  "joinedAt": "2026-04-30T08:30:00Z",
  "avatarUrl": "https://app.flownally.com/avatar/lina.png",
  "provider": "google",
  "emailVerified": true,
  "disabled": false
}