# Service User API

Source: https://userguide.qualytics.io/settings/access/service-users/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](https://userguide.qualytics.io/api/docs).

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

> **Info: 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](https://userguide.qualytics.io/settings/access/service-users/deep-dive/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 |
| `filters` | `string` (JSON) | Narrows the list by one or more filters, written as a JSON object. See [Filtering Lists](https://userguide.qualytics.io/settings/access/service-users/api/#filtering-lists). |
| `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: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/users?type=Service" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response**:
>
> ```json
> {
>   "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](https://userguide.qualytics.io/settings/access/users/how-it-works/#the-users-list) (Service Users appear in the same list with a **Service** badge).

### Filtering Lists

`GET /api/users?type=Service` accepts a `filters` parameter: a JSON object with one entry per filter, saying how that filter's values should match.

```bash
curl -G "https://your-instance.qualytics.io/api/users?type=Service" \
  --data-urlencode 'filters={"role":{"not_in":["Admin"]}}' \
  -H "Authorization: Bearer YOUR_TOKEN"
```

This returns the Service Users who aren't Admins.

| Key | Returns |
| --- | --- |
| `in` | The items that match at least one of the values. |
| `not_in` | The items that match none of the values. |
| `all_of` | The items that match every value, on filters an item can have several of, such as tags. |
| `empty` | The items with no value (`true`) or at least one (`false`), on filters an item can lack. |

- Different filters combine with AND, and so do keys on the same filter.
- `empty` can't be combined with other keys on the same filter.
- A filter sent both as its own parameter and inside `filters` returns a `422`. Put all of that filter's conditions in `filters`.
- `in`, `not_in` and `all_of` each take between 1 and 20 values.
- A filter or key the endpoint doesn't accept returns a `422` that names it. The [API docs](https://userguide.qualytics.io/api/docs) list what each endpoint accepts.

---

## Get Service User

Retrieve a single Service User by ID.

**Endpoint**: `GET /api/users/{id}`

**Permission**: Manager user role

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/users/123" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response**:
>
> ```json
> {
>   "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: Example request and response**
>
> **Request**:
>
> ```bash
> 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**:
>
> ```json
> {
>   "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](https://userguide.qualytics.io/settings/access/service-users/managing/create-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: Example request and response**
>
> **Request**:
>
> ```bash
> 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**:
>
> ```json
> {
>   "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](https://userguide.qualytics.io/settings/access/service-users/managing/edit-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

> **Warning: Active Tokens Must Be Revoked First**
>
> A Service User cannot be deactivated while it has active tokens, meaning tokens that are neither revoked nor expired. The system returns a 400 Bad Request error if you try. Revoke all active tokens before deactivating the account. Revoked and expired tokens do not block deactivation.

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> 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](https://userguide.qualytics.io/settings/access/service-users/managing/deactivate-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](https://userguide.qualytics.io/settings/access-tokens/service-token/api/) to restore individual tokens or generate new ones.

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X PATCH "https://your-instance.qualytics.io/api/users/123" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response**:
>
> ```json
> {
>   "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](https://userguide.qualytics.io/settings/access/service-users/managing/reactivate-service-user/) page.

---

## Error Responses

| Status Code | Description |
| --- | --- |
| `400 Bad Request` | Cannot deactivate Service User with active tokens (neither revoked nor expired), 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). |

> **Example: Error response examples**
>
> **403 Forbidden** (a Manager attempting to create, update, or deactivate a Service User):
>
> ```json
> { "detail": "Required role(s): ['Admin']" }
> ```
>
> **400 Bad Request** (deactivating Service User with active tokens):
>
> ```json
> { "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](https://userguide.qualytics.io/settings/access-tokens/service-token/api/) page.

*Last updated: November 13, 2026.*
