Users and groups

Manage application users and group membership within a workspace. Use developer credentials and include the workspace context required by each operation.

API conventions · All endpoints · Schemas

`/e/v1/developer/groups/`

Manage application-user groups.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_groups.

Optional list filters workspace_id and oauth_client where shown below; detail routes check resource ownership.

Request / response schema: Group.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`oauth_client`	`not supplied`
query	`workspace_id`	`not supplied`

Related schemas: Group.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

[
  {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "Example",
    "created_at": "2026-10-26T12:00:00Z",
    "updated_at": "2026-10-26T12:00:00Z",
    "created_via_api_key": "EXAMPLE_CREATED_VIA_API_KEY",
    "developer_id": "EXAMPLE_DEVELOPER_ID",
    "workspace": "11111111-1111-4111-8111-111111111111",
    "member_count": 1
  }
]

200 — json

[]

403 — json

{
  "error": "Workspace not found or access denied"
}

404 — json

{
  "error": "Workspace not found"
}

500 — json

{
  "error": "Failed to list groups from external database. Please check connection logs."
}

503 — json

{
  "error": "Custom database connection is active but not healthy. Please check the connection status or deactivate it to use internal database."
}

POST

Required developer-token scope: write_groups.

Supply workspace explicitly and the required fields in the linked schema. Plan features, quotas and resource ownership apply.

Request / response schema: Group.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`user_plan_id`	`not supplied`
body	`workspace`	`not supplied`
query	`workspace_id`	`not supplied`

Related schemas: Group.

Example request body:

{
  "name": "Developers",
  "workspace": "11111111-1111-4111-8111-111111111111",
  "description": "Test group"
}

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

201 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Example",
  "created_at": "2026-10-26T12:00:00Z",
  "updated_at": "2026-10-26T12:00:00Z",
  "created_via_api_key": "EXAMPLE_CREATED_VIA_API_KEY",
  "developer_id": "EXAMPLE_DEVELOPER_ID",
  "workspace": "11111111-1111-4111-8111-111111111111",
  "member_count": 1
}

201 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Example",
  "description": "EXAMPLE_DESCRIPTION",
  "is_active": true,
  "created_at": "EXAMPLE_CREATED_AT",
  "external_database": true
}

400 — json

JSON response varies with the request. See the operation requirements and linked schema; validation errors may be keyed by field name.

400 — json

{
  "error": "workspace_id parameter is required"
}

403 — json

{
  "error": "You do not have access to this workspace"
}

403 — json

{
  "error": "Group creation limit exceeded",
  "feature": "max_groups",
  "current_count": 1,
  "limit": 1,
  "message": "EXAMPLE_MESSAGE",
  "upgrade_message": "Please upgrade your Syauth plan to create more groups"
}

404 — json

{
  "error": "Workspace not found"
}

500 — json

{
  "error": "Failed to create group in external database. Please check connection logs."
}

503 — json

{
  "error": "Custom database connection is active but not healthy. Please check the connection status or deactivate it to use internal database."
}

`/e/v1/developer/groups/{group_id}/`

Manage application-user groups.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_groups.

Optional list filters workspace_id and oauth_client where shown below; detail routes check resource ownership.

Path parameters: group_id (uuid, required).

Request / response schema: Group.

Related schemas: Group.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Example",
  "created_at": "2026-10-26T12:00:00Z",
  "updated_at": "2026-10-26T12:00:00Z",
  "created_via_api_key": "EXAMPLE_CREATED_VIA_API_KEY",
  "developer_id": "EXAMPLE_DEVELOPER_ID",
  "workspace": "11111111-1111-4111-8111-111111111111",
  "member_count": 1
}

200 — json

JSON response varies with the request. See the operation requirements and linked schema; validation errors may be keyed by field name.

PATCH

Required developer-token scope: write_groups.

Partial update using the linked schema; resource ownership applies.

Path parameters: group_id (uuid, required).

Request / response schema: Group.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
body	`name`	`not supplied`
body	`description`	`not supplied`
query	`user_plan_id`	`not supplied`

Related schemas: Group.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Example",
  "created_at": "2026-10-26T12:00:00Z",
  "updated_at": "2026-10-26T12:00:00Z",
  "created_via_api_key": "EXAMPLE_CREATED_VIA_API_KEY",
  "developer_id": "EXAMPLE_DEVELOPER_ID",
  "workspace": "11111111-1111-4111-8111-111111111111",
  "member_count": 1
}

200 — json

JSON response varies with the request. See the operation requirements and linked schema; validation errors may be keyed by field name.

400 — json

JSON response varies with the request. See the operation requirements and linked schema; validation errors may be keyed by field name.

DELETE

Required developer-token scope: write_groups.

No body; resource ownership applies.

Path parameters: group_id (uuid, required).

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`user_plan_id`	`not supplied`

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

204 — json

No response body.

500 — json

{
  "error": "Failed to delete group from external database"
}

`/e/v1/developer/groups/{group_id}/members/`

Read or modify a group’s application-user membership.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_groups.

Required query workspace_id (legacy user_plan_id alias).

Path parameters: group_id (uuid, required).

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`workspace_id`	`not supplied`
query	`user_plan_id`	`not supplied`

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

[]

200 — json

JSON response varies with the request. See the operation requirements and linked schema; validation errors may be keyed by field name.

POST

Required developer-token scope: write_groups.

Required user_id in JSON and workspace_id query (body workspace_id also accepted in this method). User and group must belong to the workspace.

Path parameters: group_id (uuid, required).

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
body	`user_id`	`not supplied`
query	`workspace_id`	`not supplied`
body	`workspace_id`	`not supplied`
query	`user_plan_id`	`not supplied`

Example request body:

{
  "user_id": "11111111-1111-4111-8111-111111111111"
}

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "message": "User added to group"
}

200 — json

{
  "message": "User added to group",
  "external_database": true
}

400 — json

{
  "error": "workspace_id parameter is required"
}

400 — json

{
  "error": "User ID is required"
}

403 — json

{
  "error": "You do not have access to this workspace"
}

404 — json

{
  "error": "Workspace not found"
}

404 — json

{
  "error": "User not found or not created with this plan"
}

500 — json

{
  "error": "EXAMPLE_ERROR"
}

DELETE

Required developer-token scope: write_groups.

Same JSON user_id and workspace context as POST. This DELETE requires a JSON body; generic frontend DELETE proxies may not forward it.

Path parameters: group_id (uuid, required).

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
body	`user_id`	`not supplied`
query	`workspace_id`	`not supplied`
body	`workspace_id`	`not supplied`
query	`user_plan_id`	`not supplied`

Example request body:

{
  "user_id": "11111111-1111-4111-8111-111111111111"
}

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "message": "User removed from group"
}

200 — json

{
  "message": "User removed from group",
  "external_database": true
}

400 — json

{
  "error": "workspace_id parameter is required"
}

400 — json

{
  "error": "User ID is required"
}

403 — json

{
  "error": "You do not have access to this workspace"
}

404 — json

{
  "error": "Workspace not found"
}

404 — json

{
  "error": "User not found or not created with this plan"
}

500 — json

{
  "error": "Failed to remove user from group in external database"
}

`/e/v1/developer/users/search/`

Search application users by email within a workspace.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_users.

Required query email and workspace_id (legacy alias user_plan_id). Returns matching user objects; requires workspace access.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`email`	`not supplied`
query	`workspace_id`	`not supplied`
query	`user_plan_id`	`not supplied`

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

[]

400 — json

{
  "error": "Email parameter is required"
}

400 — json

{
  "error": "workspace_id parameter is required"
}

403 — json

{
  "error": "You do not have access to this workspace"
}

404 — json

{
  "error": "Workspace not found"
}

`/e/v1/developer/users/`

List or create users within accessible workspaces.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_users.

Optional query workspace_id, oauth_client, email. Pagination: limit integer default 20, capped at 100; offset integer default 0. Response uses count/results and boolean-or-null next/previous markers, not URL links.

Request / response schema: User.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`workspace_id`	`not supplied`
query	`oauth_client`	`not supplied`
query	`email`	`not supplied`
query	`offset`	`0`
query	`limit`	`20`

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": []
}

200 — json

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [],
  "source": "external_database"
}

400 — json

{
  "error": "Invalid pagination parameters. 'limit' and 'offset' must be integers."
}

400 — json

{
  "error": "Invalid pagination parameters."
}

403 — json

{
  "error": "Workspace not found or access denied"
}

403 — json

{
  "error": "OAuth client not found or access denied"
}

404 — json

{
  "error": "Workspace not found"
}

500 — json

{
  "error": "Failed to list users from external database. Please check connection logs."
}

503 — json

{
  "error": "Custom database connection is active but not healthy. Please check the connection status or deactivate it to use internal database."
}

POST

Required developer-token scope: write_users.

Required query workspace_id (legacy alias user_plan_id). JSON User schema; provide workspace, email, password, confirm_password and oauth_client for password-login users. Optional send_verification boolean defaults true. Checks workspace access and max_users quota.

Request / response schema: User.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`workspace_id`	`not supplied`
query	`user_plan_id`	`not supplied`

Related schemas: User.

Example request body:

{
  "workspace": "11111111-1111-4111-8111-111111111111",
  "oauth_client": "PUBLIC_CLIENT_ID",
  "email": "[email protected]",
  "password": "ExamplePass!7264X",
  "confirm_password": "ExamplePass!7264X",
  "send_verification": true
}

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

201 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "email": "[email protected]",
  "first_name": "Example",
  "last_name": "Example",
  "company": "EXAMPLE_COMPANY",
  "website": "https://app.example.test/callback",
  "country": "EXAMPLE_COUNTRY",
  "job_title": "EXAMPLE_JOB_TITLE",
  "phone_number": "EXAMPLE_PHONE_NUMBER",
  "email_verified": true,
  "created_at": "2026-10-26T12:00:00Z",
  "updated_at": "2026-10-26T12:00:00Z",
  "last_login": "2026-10-26T12:00:00Z",
  "created_via_api_key": "EXAMPLE_CREATED_VIA_API_KEY",
  "developer_id": "EXAMPLE_DEVELOPER_ID",
  "workspace": "11111111-1111-4111-8111-111111111111",
  "oauth_client": "11111111-1111-4111-8111-111111111111"
}

201 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "email": "[email protected]",
  "first_name": "Example",
  "last_name": "Example",
  "email_verified": true,
  "created_at": "EXAMPLE_CREATED_AT",
  "external_database": true
}

400 — json

JSON response varies with the request. See the operation requirements and linked schema; validation errors may be keyed by field name.

400 — json

{
  "error": "workspace_id parameter is required"
}

400 — json

{
  "error": "Workspace is required. Please provide a workspace or create one first."
}

403 — json

{
  "error": "You do not have access to this workspace"
}

403 — json

{
  "error": "User creation limit exceeded",
  "feature": "max_users",
  "current_count": 1,
  "limit": 1,
  "message": "EXAMPLE_MESSAGE",
  "upgrade_message": "Please upgrade your Syauth plan to create more users"
}

404 — json

{
  "error": "Workspace not found"
}

500 — json

{
  "error": "Failed to create user: EXAMPLE"
}

500 — json

{
  "error": "Failed to create user in external database"
}

`/e/v1/developer/users/{user_id}/`

Read, update or remove an application user.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_users.

Required workspace context via query workspace_id (legacy alias user_plan_id) for SyAuth-managed user lookup.

Path parameters: user_id (uuid, required).

Request / response schema: User.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`workspace_id`	`not supplied`
query	`user_plan_id`	`not supplied`

Related schemas: User.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "email": "[email protected]",
  "first_name": "Example",
  "last_name": "Example",
  "company": "EXAMPLE_COMPANY",
  "website": "https://app.example.test/callback",
  "country": "EXAMPLE_COUNTRY",
  "job_title": "EXAMPLE_JOB_TITLE",
  "phone_number": "EXAMPLE_PHONE_NUMBER",
  "email_verified": true,
  "created_at": "2026-10-26T12:00:00Z",
  "updated_at": "2026-10-26T12:00:00Z",
  "last_login": "2026-10-26T12:00:00Z",
  "created_via_api_key": "EXAMPLE_CREATED_VIA_API_KEY",
  "developer_id": "EXAMPLE_DEVELOPER_ID",
  "workspace": "11111111-1111-4111-8111-111111111111",
  "oauth_client": "11111111-1111-4111-8111-111111111111"
}

200 — json

JSON response varies with the request. See the operation requirements and linked schema; validation errors may be keyed by field name.

PUT

Required developer-token scope: write_users.

User schema update; external database branch updates first_name and last_name. Supply workspace query.

Path parameters: user_id (uuid, required).

Request / response schema: User.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
body	`first_name`	`not supplied`
body	`last_name`	`not supplied`
query	`workspace_id`	`not supplied`
query	`user_plan_id`	`not supplied`

Related schemas: User.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "email": "[email protected]",
  "first_name": "Example",
  "last_name": "Example",
  "company": "EXAMPLE_COMPANY",
  "website": "https://app.example.test/callback",
  "country": "EXAMPLE_COUNTRY",
  "job_title": "EXAMPLE_JOB_TITLE",
  "phone_number": "EXAMPLE_PHONE_NUMBER",
  "email_verified": true,
  "created_at": "2026-10-26T12:00:00Z",
  "updated_at": "2026-10-26T12:00:00Z",
  "last_login": "2026-10-26T12:00:00Z",
  "created_via_api_key": "EXAMPLE_CREATED_VIA_API_KEY",
  "developer_id": "EXAMPLE_DEVELOPER_ID",
  "workspace": "11111111-1111-4111-8111-111111111111",
  "oauth_client": "11111111-1111-4111-8111-111111111111"
}

200 — json

JSON response varies with the request. See the operation requirements and linked schema; validation errors may be keyed by field name.

400 — json

JSON response varies with the request. See the operation requirements and linked schema; validation errors may be keyed by field name.

PATCH

Required developer-token scope: write_users.

Partial User schema; supply workspace query. Password updates are rejected by this endpoint.

Path parameters: user_id (uuid, required).

Request / response schema: User.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`workspace_id`	`not supplied`
query	`user_plan_id`	`not supplied`

Related schemas: User.

Example request body:

{
  "first_name": "Updated"
}

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "email": "[email protected]",
  "first_name": "Example",
  "last_name": "Example",
  "company": "EXAMPLE_COMPANY",
  "website": "https://app.example.test/callback",
  "country": "EXAMPLE_COUNTRY",
  "job_title": "EXAMPLE_JOB_TITLE",
  "phone_number": "EXAMPLE_PHONE_NUMBER",
  "email_verified": true,
  "created_at": "2026-10-26T12:00:00Z",
  "updated_at": "2026-10-26T12:00:00Z",
  "last_login": "2026-10-26T12:00:00Z",
  "created_via_api_key": "EXAMPLE_CREATED_VIA_API_KEY",
  "developer_id": "EXAMPLE_DEVELOPER_ID",
  "workspace": "11111111-1111-4111-8111-111111111111",
  "oauth_client": "11111111-1111-4111-8111-111111111111"
}

400 — json

JSON response varies with the request. See the operation requirements and linked schema; validation errors may be keyed by field name.

DELETE

Required developer-token scope: write_users.

No body. Supply workspace query. External-store deletion can fail separately.

Path parameters: user_id (uuid, required).

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`workspace_id`	`not supplied`
query	`user_plan_id`	`not supplied`

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

204 — json

No response body.

500 — json

{
  "error": "Failed to delete user from external database"
}

`/e/v1/developer/user-group-assignments/`

Read a user’s groups or add/remove an assignment.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

POST

Required developer-token scope: write_groups.

Required query workspace_id and JSON user_id/group_id UUIDs.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
body	`user_id`	`not supplied`
body	`group_id`	`not supplied`
query	`workspace_id`	`not supplied`
query	`user_plan_id`	`not supplied`

Example request body:

{
  "user_id": "11111111-1111-4111-8111-111111111111",
  "group_id": "22222222-2222-4222-8222-222222222222"
}

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "message": "User successfully added to group"
}

200 — json

{
  "message": "User successfully added to group",
  "external_database": true
}

400 — json

{
  "error": "user_id and group_id are required"
}

400 — json

{
  "error": "workspace_id parameter is required"
}

400 — json

{
  "error": "EXAMPLE_ERROR"
}

403 — json

{
  "error": "You do not have access to this workspace"
}

404 — json

{
  "error": "Workspace not found"
}

404 — json

{
  "error": "User not found or not created under this plan"
}

404 — json

{
  "error": "Group not found or not created under this plan"
}

DELETE

Required developer-token scope: write_groups.

Required query workspace_id and JSON user_id/group_id UUIDs. Send directly to backend when a proxy drops DELETE bodies.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
body	`user_id`	`not supplied`
body	`group_id`	`not supplied`
query	`workspace_id`	`not supplied`
query	`user_plan_id`	`not supplied`

Example request body:

{
  "user_id": "11111111-1111-4111-8111-111111111111",
  "group_id": "22222222-2222-4222-8222-222222222222"
}

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "message": "User successfully removed from group"
}

200 — json

{
  "message": "User successfully removed from group",
  "external_database": true
}

400 — json

{
  "error": "user_id and group_id are required"
}

400 — json

{
  "error": "workspace_id parameter is required"
}

403 — json

{
  "error": "You do not have access to this workspace"
}

404 — json

{
  "error": "Workspace not found"
}

404 — json

{
  "error": "User not found or not created under this plan"
}

404 — json

{
  "error": "Group not found or not created under this plan"
}

500 — json

{
  "error": "Failed to remove user from group in external database"
}

GET

Required developer-token scope: read_groups.

Required query user_id, workspace_id (legacy user_plan_id alias).

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`user_id`	`not supplied`
query	`workspace_id`	`not supplied`
query	`user_plan_id`	`not supplied`

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

[]

200 — json

JSON response varies with the request. See the operation requirements and linked schema; validation errors may be keyed by field name.

400 — json

{
  "error": "user_id parameter is required"
}

400 — json

{
  "error": "workspace_id parameter is required"
}

403 — json

{
  "error": "You do not have access to this workspace"
}

404 — json

{
  "error": "Workspace not found"
}

404 — json

{
  "error": "User not found or not created under this plan"
}

/e/v1/developer/groups/​

GET​

POST​

/e/v1/developer/groups/{group_id}/​

GET​

PATCH​

DELETE​

/e/v1/developer/groups/{group_id}/members/​

GET​

POST​

DELETE​

/e/v1/developer/users/search/​

GET​

/e/v1/developer/users/​

GET​

POST​

/e/v1/developer/users/{user_id}/​

GET​

PUT​

PATCH​

DELETE​

/e/v1/developer/user-group-assignments/​

POST​

DELETE​

GET​

`/e/v1/developer/groups/`

GET

POST

`/e/v1/developer/groups/{group_id}/`

GET

PATCH

DELETE

`/e/v1/developer/groups/{group_id}/members/`

GET

POST

DELETE

`/e/v1/developer/users/search/`

GET

`/e/v1/developer/users/`

GET

POST

`/e/v1/developer/users/{user_id}/`

GET

PUT

PATCH

DELETE

`/e/v1/developer/user-group-assignments/`

POST

DELETE

GET