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

All Service User operations require 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: Admin user role

Query Parameters:

Parameter	Type	Description
`type`	string	Filter by user type. Use `Service` to list only Service Users.
`sort`	string	Sort field (e.g., `name`, `created`, `role`, `last_login`)
`sort_dir`	string	Sort direction (`asc` or `desc`)
`name`	string	Filter by user name (partial match)
`role`	string	Filter by role (`Admin`, `Manager`, `Member`)
`team`	string	Filter by team name
`include_deleted`	boolean	Include deactivated Service Users in results

Example request and response

Request:

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

Response:

{
  "total_count": 2,
  "items": [
    {
      "id": 123,
      "user_id": "svc_airflow@service",
      "user_name": "svc_airflow",
      "email": "svc_airflow@service",
      "name": "Airflow Service User",
      "role": "Manager",
      "user_type": "Service",
      "teams": ["Public", "Data Engineering"],
      "last_login": "2026-04-09T14:22:15Z",
      "created_at": "2026-01-15T10:30:00Z",
      "deleted_at": null
    },
    {
      "id": 124,
      "user_id": "svc_dbt@service",
      "user_name": "svc_dbt",
      "email": "svc_dbt@service",
      "name": "dbt Cloud Integration",
      "role": "Member",
      "user_type": "Service",
      "teams": ["Public", "Data Quality"],
      "last_login": "2026-04-08T09:15:00Z",
      "created_at": "2026-03-01T08:00:00Z",
      "deleted_at": null
    }
  ]
}

For the UI equivalent, see the Users List Columns page (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: Admin 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,
  "user_id": "svc_airflow@service",
  "user_name": "svc_airflow",
  "email": "svc_airflow@service",
  "name": "Airflow Service User",
  "role": "Manager",
  "user_type": "Service",
  "teams": ["Public", "Data Engineering"],
  "last_login": "2026-04-09T14:22:15Z",
  "created_at": "2026-01-15T10:30:00Z",
  "deleted_at": null
}

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`	Yes	The User Role: `Admin`, `Manager`, or `Member`.
`teams`	array of `string`	No	Team names the Service User should belong to. The Public team is automatically included.

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,
  "user_id": "airflow_service_user@service",
  "user_name": "airflow_service_user",
  "email": "airflow_service_user@service",
  "name": "Airflow Service User",
  "role": "Manager",
  "user_type": "Service",
  "teams": ["Public", "Data Engineering"],
  "last_login": null,
  "created_at": "2026-04-09T10:30:00Z",
  "deleted_at": null
}

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`	No	The new role (`Admin`, `Manager`, or `Member`).
`teams`	array of `string`	No	The full list of team names the Service User should belong to. Replaces existing assignments.

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,
  "user_id": "airflow_service_user@service",
  "user_name": "airflow_service_user",
  "email": "airflow_service_user@service",
  "name": "Airflow Service User",
  "role": "Member",
  "user_type": "Service",
  "teams": ["Public", "Data Quality"],
  "last_login": "2026-04-09T14:22:15Z",
  "created_at": "2026-01-15T10:30:00Z",
  "deleted_at": null
}

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:

{
  "id": 123,
  "user_id": "airflow_service_user@service",
  "user_name": "airflow_service_user",
  "email": "airflow_service_user@service",
  "name": "Airflow Service User",
  "role": "Member",
  "user_type": "Service",
  "teams": ["Public", "Data Quality"],
  "last_login": "2026-04-09T14:22:15Z",
  "created_at": "2026-01-15T10:30:00Z",
  "deleted_at": "2026-04-10T11:00:00Z"
}

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,
  "user_id": "airflow_service_user@service",
  "user_name": "airflow_service_user",
  "email": "airflow_service_user@service",
  "name": "Airflow Service User",
  "role": "Member",
  "user_type": "Service",
  "teams": ["Public", "Data Quality"],
  "last_login": "2026-04-09T14:22:15Z",
  "created_at": "2026-01-15T10:30:00Z",
  "deleted_at": null
}

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 invalid request body.
`401 Unauthorized`	Missing or invalid API token.
`403 Forbidden`	User does not have the Admin role.
`404 Not Found`	Service User with the specified ID does not exist.
`422 Unprocessable Entity`	Invalid field values (e.g., invalid role or team names).

Error response examples

403 Forbidden (non-admin attempting to manage Service Users):

{ "detail": "Only admins can manage tokens for service users" }

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	Admin user role
Get Service User details	Admin 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

All Service User operations require the Admin role. To manage tokens for Service Users, see the Service Token API page.