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) inresult.value.
- GET /clients/(client_id)¶
- GET /clients/¶
List API clients. If
client_idis given, only the matching client is returned; otherwise all clients are listed.The API key is never included; only the non-sensitive
key_idis.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) inresult.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
realmis 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 requestedrealm, 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.valueis 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 at1000.realm – optional realm name to narrow the listing to.
- Status Codes:
200 OK –
result.valueis a dict withdevices(this page),count(total matching devices),prevandnext(page numbers, ornullwhen there is no such page).404 Not Found – no client with that id exists, or
realmdoes 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 (usertogether withrealm).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
realmso the user resolves unambiguously.
- Status Codes:
200 OK –
result.valueis 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.valueis 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.valueis the id of the deleted client.404 Not Found – no client with that id exists.