16.1.1.18. privacyIDEA Server endpoints

The privacyIDEA-server REST API manages definitions of remote privacyIDEA servers. These definitions are referenced by the Remote token type to forward authentication requests, and by the Federation Handler Module event handler to chain privacyIDEA instances. See privacyIDEA server configuration for the conceptual chapter.

All endpoints require admin authentication. Read access is gated by the admin policy action privacyideaserver_read; create, update, delete and the test request are gated by privacyideaserver_write.

POST /privacyideaserver/(identifier)

Create or update a privacyIDEA server definition. If a definition with the given identifier already exists it is updated; otherwise it is created. Spaces in identifier are replaced with underscores.

Requires admin authentication and the policy action privacyideaserver_write.

Parameters:

  • identifier – path component, the unique name of the definition.

JSON Parameters:

  • url – URL of the remote privacyIDEA server (required).

  • tls – 1 (default) to verify the TLS certificate of the remote server, 0 to skip verification.

  • description – free-form description.

Status Codes:
GET /privacyideaserver/

Return all privacyIDEA server definitions known to this server.

The result is a dictionary keyed by identifier; each value contains id, url, tls and description.

Requires admin authentication and the policy action privacyideaserver_read.

Status Codes:

  • 200 OK – dict of definitions in result.value.

DELETE /privacyideaserver/(identifier)

Delete the privacyIDEA server definition with the given identifier.

Requires admin authentication and the policy action privacyideaserver_write.

Parameters:

  • identifier – path component, the name of the definition.

Status Codes:

  • 200 OK – True if a definition was deleted, False otherwise.

POST /privacyideaserver/test_request

Test a privacyIDEA server definition by sending an authentication request to it. The handler issues POST /validate/check against the supplied url using the given username and password, with TLS verification controlled by tls. The definition does not need to be saved first — all parameters are taken from the request body.

Requires admin authentication and the policy action privacyideaserver_write.

JSON Parameters:

  • identifier – identifier under which the definition would be saved (used for logging/audit only).

  • url – URL of the remote privacyIDEA server (required).

  • tls – 1 (default) to verify the TLS certificate of the remote server, 0 to skip verification.

  • username – user name to test (required).

  • password – password / OTP to test (required).

Status Codes:

  • 200 OK – True if the remote server accepted the credentials, False otherwise.