Service User API

The Service User API allows administrators to create, list, update, deactivate, and reactivate Service Users programmatically.

Tip

For complete API documentation, including request/response schemas, visit the API docs.

All endpoints are served from your Qualytics deployment (e.g., https://your-instance.qualytics.io). The paths below include the /api prefix.

Prerequisite

Listing and viewing Service Users requires the Manager role or above. Creating, updating, deactivating, and reactivating them requires the Admin role. See Service User Permissions for details.

List Service Users

Retrieve a paginated list of Service Users with optional filters.

Endpoint: GET /api/users?type=Service

Permission: Manager user role

Query Parameters:

Parameter	Type	Description
`type`	string	Filter by user type: `Service` or `Human`. Use `Service` to list only Service Users.
`name`	string	Filter by user name or email (partial match, not case-sensitive)
`role`	string	Filter by role (`Admin`, `Manager`, `Member`)
`team`	string	Filter by team name. Repeat the parameter to filter by more than one team.
`status`	string	Filter by account status: `Active` or `Inactive`. `Inactive` returns deactivated Service Users.
`include_deleted`	boolean	Include deactivated Service Users in results
`sort_name`, `sort_created`, `sort_role`, `sort_team`, `sort_status`, `sort_type`, `sort_last_login`	string	Sort by name, creation date, role, number of teams, status, user type, or last login. Each takes `asc` or `desc`.
`page`	integer	Page number, starting at `1`.
`size`	integer	Results per page. Default `50`, maximum `100`.

Example request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/users?type=Service" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "items": [
    {
      "id": 123,
      "created": "2026-01-15T10:30:00Z",
      "user_id": "airflow_service_user@service",
      "user_name": "airflow_service_user@service",
      "email": null,
      "name": "Airflow Service User",
      "picture": null,
      "role": "Manager",
      "user_type": "Service",
      "last_login": "2026-04-09T14:22:15Z",
      "deleted_at": null,
      "teams": [
        {
          "id": -1,
          "name": "Public",
          "display_name": null,
          "display_label": "Public",
          "permission": "Viewer"
        },
        {
          "id": 7,
          "name": "Data Engineering",
          "display_name": null,
          "display_label": "Data Engineering",
          "permission": "Editor"
        }
      ],
      "oidc_groups": [],
      "is_team_restricted": false
    },
    {
      "id": 124,
      "created": "2026-03-01T08:00:00Z",
      "user_id": "dbt_cloud_integration@service",
      "user_name": "dbt_cloud_integration@service",
      "email": null,
      "name": "dbt Cloud Integration",
      "picture": null,
      "role": "Member",
      "user_type": "Service",
      "last_login": "2026-04-08T09:15:00Z",
      "deleted_at": null,
      "teams": [
        {
          "id": -1,
          "name": "Public",
          "display_name": null,
          "display_label": "Public",
          "permission": "Viewer"
        },
        {
          "id": 9,
          "name": "Data Quality",
          "display_name": null,
          "display_label": "Data Quality",
          "permission": "Author"
        }
      ],
      "oidc_groups": [],
      "is_team_restricted": false
    }
  ],
  "total": 2,
  "page": 1,
  "size": 50,
  "pages": 1
}

For the UI equivalent, see The Users List (Service Users appear in the same list with a Service badge).

Get Service User

Retrieve a single Service User by ID.

Endpoint: GET /api/users/{id}

Permission: Manager user role

Example request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/users/123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "id": 123,
  "created": "2026-01-15T10:30:00Z",
  "user_id": "airflow_service_user@service",
  "user_name": "airflow_service_user@service",
  "email": null,
  "name": "Airflow Service User",
  "picture": null,
  "role": "Manager",
  "user_type": "Service",
  "last_login": "2026-04-09T14:22:15Z",
  "deleted_at": null,
  "teams": [
    {
      "id": -1,
      "name": "Public",
      "display_name": null,
      "display_label": "Public",
      "permission": "Viewer"
    },
    {
      "id": 7,
      "name": "Data Engineering",
      "display_name": null,
      "display_label": "Data Engineering",
      "permission": "Editor"
    }
  ],
  "oidc_groups": [],
  "is_team_restricted": false
}

Create Service User

Create a new Service User for automation and integrations.

Endpoint: POST /api/users

Permission: Admin user role

Request Body:

Field	Type	Required	Description
`name`	`string`	Yes	A descriptive name for the Service User. The system auto-generates an internal ID with the `@service` suffix.
`role`	`string`	No	The User Role: `Admin`, `Manager`, or `Member`. Defaults to `Member`.
`teams`	array of `string`	No	Team names the Service User should belong to. The Public team is automatically included. Names must match an existing team exactly, including case. A name that matches no team creates a new team with the Viewer team permission.

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/users" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Airflow Service User",
    "role": "Manager",
    "teams": ["Data Engineering"]
  }'

Response:

{
  "id": 123,
  "created": "2026-04-09T10:30:00Z",
  "user_id": "airflow_service_user@service",
  "user_name": "airflow_service_user@service",
  "email": null,
  "name": "Airflow Service User",
  "picture": null,
  "role": "Manager",
  "user_type": "Service",
  "last_login": null,
  "deleted_at": null,
  "teams": [
    {
      "id": -1,
      "name": "Public",
      "display_name": null,
      "display_label": "Public",
      "permission": "Viewer"
    },
    {
      "id": 7,
      "name": "Data Engineering",
      "display_name": null,
      "display_label": "Data Engineering",
      "permission": "Editor"
    }
  ],
  "oidc_groups": [],
  "is_team_restricted": false
}

For the UI equivalent, see the Create a Service User page.

Update Service User

Update a Service User's role or team assignments.

Endpoint: PUT /api/users/{id}

Permission: Admin user role

Request Body:

Field	Type	Required	Description
`role`	`string`	Yes	The role (`Admin`, `Manager`, or `Member`). Send the current role to keep it unchanged.
`teams`	array of `string`	No	The full list of team names the Service User should belong to. Replaces existing assignments. Names must match an existing team exactly, including case. A name that matches no team creates a new team with the Viewer team permission.

Example request and response

Request:

curl -X PUT "https://your-instance.qualytics.io/api/users/123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "Member",
    "teams": ["Data Quality"]
  }'

Response:

{
  "id": 123,
  "created": "2026-01-15T10:30:00Z",
  "user_id": "airflow_service_user@service",
  "user_name": "airflow_service_user@service",
  "email": null,
  "name": "Airflow Service User",
  "picture": null,
  "role": "Member",
  "user_type": "Service",
  "last_login": "2026-04-09T14:22:15Z",
  "deleted_at": null,
  "teams": [
    {
      "id": -1,
      "name": "Public",
      "display_name": null,
      "display_label": "Public",
      "permission": "Viewer"
    },
    {
      "id": 9,
      "name": "Data Quality",
      "display_name": null,
      "display_label": "Data Quality",
      "permission": "Author"
    }
  ],
  "oidc_groups": [],
  "is_team_restricted": false
}

For the UI equivalent, see the Edit a Service User page.

Deactivate Service User

Soft-delete a Service User. The account is preserved and can be reactivated later.

Endpoint: DELETE /api/users/{id}

Permission: Admin user role

Active Tokens Must Be Revoked First

A Service User cannot be deactivated while it has active tokens. The system returns a 400 Bad Request error if you try. Revoke all active tokens before deactivating the account.

Example request and response

Request:

curl -X DELETE "https://your-instance.qualytics.io/api/users/123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (204 No Content): the response has no body.

For the UI equivalent, see the Deactivate a Service User page.

Reactivate Service User

Restore a previously deactivated Service User.

Endpoint: PATCH /api/users/{id}

Permission: Admin user role

Note

Reactivation restores the Service User account but does not automatically restore previously revoked tokens. Use the Service Token API to restore individual tokens or generate new ones.

Example request and response

Request:

curl -X PATCH "https://your-instance.qualytics.io/api/users/123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "id": 123,
  "created": "2026-01-15T10:30:00Z",
  "user_id": "airflow_service_user@service",
  "user_name": "airflow_service_user@service",
  "email": null,
  "name": "Airflow Service User",
  "picture": null,
  "role": "Member",
  "user_type": "Service",
  "last_login": "2026-04-09T14:22:15Z",
  "deleted_at": null,
  "teams": [
    {
      "id": -1,
      "name": "Public",
      "display_name": null,
      "display_label": "Public",
      "permission": "Viewer"
    },
    {
      "id": 9,
      "name": "Data Quality",
      "display_name": null,
      "display_label": "Data Quality",
      "permission": "Author"
    }
  ],
  "oidc_groups": [],
  "is_team_restricted": false
}

For the UI equivalent, see the Reactivate a Service User page.

Error Responses

Status Code	Description
`400 Bad Request`	Cannot deactivate Service User with active tokens, or the `name` has no characters that can form the Service User's ID.
`401 Unauthorized`	Missing or invalid API token.
`403 Forbidden`	User does not have the required role: Manager to list or view Service Users, Admin for every other operation.
`404 Not Found`	Service User with the specified ID does not exist.
`409 Conflict`	A user with the same generated Service User ID already exists, including a deactivated one. Names that differ only in case or punctuation, such as `Foo-Bar` and `FooBar`, produce the same ID.
`422 Unprocessable Entity`	Invalid field values (e.g., an invalid role).

Error response examples

403 Forbidden (a Manager attempting to create, update, or deactivate a Service User):

{ "detail": "Required role(s): ['Admin']" }

400 Bad Request (deactivating Service User with active tokens):

{ "detail": "Cannot delete service user with active tokens. Revoke tokens first" }

Permission Summary

Operation	Minimum Permission
List Service Users	Manager user role
Get Service User details	Manager user role
Create Service User	Admin user role
Update Service User	Admin user role
Deactivate Service User	Admin user role
Reactivate Service User	Admin user role

Info

Changing Service Users requires the Admin role. Managers can only list and view them. To manage tokens for Service Users, see the Service Token API page.