16.1.1.33. API client endpoints

The clients REST API manages API clients. An API client authenticates against privacyIDEA with an API key sent in the X-API-Key header.

The plaintext API key is returned to the administrator exactly once, in the response of the creation and the rotation endpoints. It is never stored and can never be retrieved again; if it is lost, the key must be rotated.

All endpoints require admin authentication. Listing is gated by the admin policy action api_client_list, creation by api_client_add, modification by api_client_edit, deletion by api_client_delete and key rotation by api_client_rotate. The remembered-device endpoints are gated by remembered_device_list and remembered_device_revoke.

POST /clients/

Create a new API client and generate its API key.

The freshly generated plaintext API key is returned in result.value.api_key. This is the only time the key is exposed, so it must be shown to the administrator and cannot be retrieved later.

Requires admin authentication and the policy action api_client_add.

JSON Parameters:
  • display_name – a human readable name for the client.

  • client_type – one of the API-client integrations from GET /info/integrations, e.g. ‘privacyidea-cp’, ‘privacyidea-keycloak’, ‘entraid-via-keycloak’.

  • config – optional JSON object for future remote configuration.

Status Codes:
  • 200 OK – the client (including api_key) in result.value.

GET /clients/(client_id)
GET /clients/

List API clients. If client_id is given, only the matching client is returned; otherwise all clients are listed.

The API key is never included; only the non-sensitive key_id is.

Requires admin authentication and the policy action api_client_list.

Parameters:
  • client_id – optional path component selecting a single client.

Status Codes:
  • 200 OK – a list of clients in result.value.

PATCH /clients/(client_id)

Partially update the metadata of an existing client (display name, status or config); only the fields present in the request are changed. The API key is not affected; use the rotate endpoint to replace it.

Requires admin authentication and the policy action api_client_edit.

Parameters:
  • client_id – path component, the id of the client.

JSON Parameters:
  • display_name – the new display name.

  • status – the new status (‘active’ or ‘suspended’).

  • config – the new config object.

Status Codes:
  • 200 OK – the updated client in result.value.

POST /clients/(client_id)/rotate

Rotate the API key of a client. The previous key is invalidated immediately and a new plaintext key is returned in result.value.api_key. As with creation, this is the only time the new key is exposed.

Requires admin authentication and the policy action api_client_rotate.

Parameters:
  • client_id – path component, the id of the client.

Status Codes:
  • 200 OK – the client (including the new api_key) in result.value.

DELETE /clients/remembered_devices

Revoke remembered devices across all clients, scoped to a realm or to a single user. This is the client-independent bulk revoke, for realm-wide incident response or offboarding a single user.

A realm is always required (a user is identified within a realm), so this can never wipe every device on the system at once. The acting administrator’s realm restrictions apply: the remembered_device_revoke action is matched against the requested realm, so a realm-scoped admin cannot revoke another realm’s devices.

Requires admin authentication and the policy action remembered_device_revoke.

Query Parameters:
  • realm – the realm whose devices to revoke (required).

  • user – optional login to restrict the revocation to a single user within the realm.

Status Codes:
  • 200 OK – result.value is the number of revoked remembered devices.

GET /clients/(client_id)/remembered_devices

List the remembered devices of a client.

No part of the cookie is ever included; each entry carries only a non-secret device_id (used to target revocation) and metadata (user, IP, user agent, created / last used / expiry).

The listing is paginated: a client shared across many browsers/devices per user can accumulate a very large number of remembered devices.

Requires admin authentication and the policy action remembered_device_list.

Parameters:
  • client_id – path component, the id of the client.

Query Parameters:
  • page – 1-indexed page number, default 1; values below 1 are treated as 1.

  • pagesize – page size, default 50, capped at 1000.

  • realm – optional realm name to narrow the listing to.

Status Codes:
  • 200 OK – result.value is a dict with devices (this page), count (total matching devices), prev and next (page numbers, or null when there is no such page).

  • 404 Not Found – no client with that id exists, or realm does not exist.

DELETE /clients/(client_id)/remembered_devices

Revoke remembered devices of a client in bulk. Without a filter this revokes all of the client’s remembered devices; it can be narrowed to one realm (realm) or to one user (user together with realm).

The delete is a single atomic, server-side operation scoped to the client, so a client id cannot revoke another client’s devices, and devices created between listing and revoking are still caught.

Requires admin authentication and the policy action remembered_device_revoke.

Parameters:
  • client_id – path component, the id of the client.

Query Parameters:
  • realm – optional, restrict the revocation to this realm.

  • user – optional, restrict the revocation to this user (login); requires realm so the user resolves unambiguously.

Status Codes:
  • 200 OK – result.value is the number of revoked remembered devices.

  • 404 Not Found – no client with that id exists.

DELETE /clients/(client_id)/remembered_devices/(device_id)

Revoke a single remembered device of a client, targeted by its non-secret device_id. The revocation is scoped to the client, so a client id cannot be used to revoke another client’s device.

Requires admin authentication and the policy action remembered_device_revoke.

Parameters:
  • client_id – path component, the id of the client.

  • device_id – path component, the public device id (never the cookie’s secret series id).

Status Codes:
  • 200 OK – result.value is the device id of the revoked remembered device.

  • 404 Not Found – no such device exists for this client, or it belongs to a realm the acting admin may not revoke in - the two are deliberately indistinguishable.

DELETE /clients/(client_id)

Delete the client with the given id.

Requires admin authentication and the policy action api_client_delete.

Parameters:
  • client_id – path component, the id of the client.

Status Codes:
  • 200 OK – result.value is the id of the deleted client.

  • 404 Not Found – no client with that id exists.