16.1.1.4. System endpoints

The system REST API exposes the server’s configuration store and a handful of operational endpoints: the HSM unlock, an entropy source, per-token configuration tests, the rendered system documentation, and listings of configured RADIUS servers, CA connectors and nodes. See System Config for the conceptual chapter.

Most endpoints require admin authentication. Create/update and the setDefault shortcut are gated by the policy action configwrite, configread, configdelete; deletion by configwrite, configread, configdelete. The rendered documentation requires system_documentation, the HSM unlock requires set_hsm_password, and the entropy endpoint requires getrandom. GET /system/ / GET /system/<key> may be called by any authenticated user; non-admin callers only see configuration entries flagged as public.

GET /system/documentation

Render the current server configuration (system config, app config, resolvers, realms, policies, admin accounts) into a single reStructuredText document. The response is text/plain; consumers typically pipe it through Sphinx to produce a rendered status report.

Requires admin authentication and the policy action system_documentation.

Status Codes:

  • 200 OK – text/plain body containing the rendered document.

GET /system/gpgkeys

Return the public GPG keys held in the directory configured via PI_GNUPG_HOME. These keys are used to verify imported token seed files.

Requires admin authentication.

Status Codes:

  • 200 OK – dict of public GPG keys (keyed by fingerprint) in result.value.

GET /system/(key)
GET /system/

Return system configuration.

Without a path component, returns all configuration entries as a dictionary. With <key> in the path, returns only that entry’s value.

Both admins and authenticated users may call this endpoint, but non-admins only see configuration entries that are flagged as public. Querying a non-public key as a regular user returns null. Admin access is gated by the policy action policy_configread when at least one configread policy is defined.

Parameters:

  • key – optional path component, the configuration key to fetch.

Request Headers:

  • PI-Authorization – authentication token.

Status Codes:

  • 200 OK – configuration dictionary or single value in result.value.

Example request:

GET /system/ HTTP/1.1
Host: example.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": {
      "AutoResync": "False",
      "splitAtSign": "True",
      "PrependPin": "True",
      "DefaultCountWindow": "10"
    }
  },
  "version": "privacyIDEA unknown"
}

Example request (single key):

GET /system/totp.hashlib HTTP/1.1
Host: example.com
Accept: application/json

Example response (single key):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": "sha1"
  },
  "version": "privacyIDEA unknown"
}
POST /system/setConfig

Set one or more system configuration entries. The body is a flat dictionary of keyname: value pairs; per-entry metadata may be supplied using keyname.type and keyname.desc companion keys. Setting keyname.type to password causes the value to be stored encrypted.

Requires admin authentication and the policy action configwrite, configread, configdelete.

JSON Parameters:

  • <keyname> – configuration value to store.

  • <keyname>.type – optional type tag — int, string, text, or password (encrypted at rest).

  • <keyname>.desc – optional human-readable description.

Request Headers:

  • PI-Authorization – authentication token.

Status Codes:

  • 200 OK – dict mapping each set key to "insert" or "update" in result.value.

Example request:

POST /system/setConfig HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "splitAtSign": true,
  "totp.hashlib": "sha1",
  "totp.hashlib.desc": "The hash algorithm used for TOTP tokens"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": {
      "splitAtSign": "update",
      "totp.hashlib": "update"
    }
  },
  "version": "privacyIDEA unknown"
}
POST /system/setDefault

Set token default values that apply to newly enrolled tokens. Existing tokens are not affected. At least one of the listed parameters must be supplied.

Requires admin authentication and the policy action configwrite, configread, configdelete.

JSON Parameters:

  • DefaultMaxFailCount – maximum allowed authentication failures before a token is locked.

  • DefaultSyncWindow – synchronization window size.

  • DefaultCountWindow – counter window size.

  • DefaultOtpLen – OTP value length (typically 6 or 8).

  • DefaultResetFailCount – whether the fail counter should be reset on successful authentication (True / False).

Status Codes:

  • 200 OK – dict mapping each updated key to "insert" or "update" in result.value.

  • 400 Bad Request – none of the listed parameters was supplied.

DELETE /system/(key)

Delete a system configuration entry.

Requires admin authentication and the policy action configwrite, configread, configdelete.

Parameters:

  • key – path component, the configuration key to delete.

Status Codes:

  • 200 OK – True on success in result.value.

POST /system/hsm

Provide the password for the configured security module (HSM / PKCS#11) so privacyIDEA can unlock its encryption key. Until the HSM is unlocked, tokens whose secrets are protected by the HSM cannot be used.

Requires admin authentication and the policy action set_hsm_password.

JSON Parameters:

  • password – the security-module password (required).

Status Codes:

  • 200 OK – {"is_ready": <bool>} in result.value; True if the HSM is now unlocked.

GET /system/hsm

Return the readiness state of the configured security module.

Requires admin authentication.

Status Codes:

  • 200 OK – {"is_ready": <bool>} in result.value; True if the HSM is unlocked and usable.

GET /system/random

Return cryptographically random bytes from the server’s RNG. Clients use this when seeding tokens (CLI initializing a Yubikey, WebUI creating a token secret) so that the secret material is sourced from a trusted, centrally audited generator — and, when privacyIDEA is configured against an HSM, from the HSM’s hardware RNG.

Requires admin authentication and the policy action getrandom.

Query Parameters:

  • len – number of random bytes to return; default 20.

  • encode – encoding for the result — hex (default) or b64.

Status Codes:

  • 200 OK – the encoded random bytes in result.value.

POST /system/test/(tokentype)

Probe the server-side configuration of a given token type by invoking that token class’ test_config classmethod with the request body. The shape of the body and what the test actually does are token-type specific (the email token, for example, sends a test email through the configured SMTP server).

Requires admin authentication and the policy action configwrite, configread, configdelete.

Parameters:

  • tokentype – path component, the token type to test (e.g. email).

Jsonparam:

any token-type-specific configuration fields.

Status Codes:

  • 200 OK – True if the configuration is valid, False otherwise; detail.message carries a human-readable description.

GET /system/names/radius

Return the identifiers of all configured RADIUS servers (only the names, not the full configurations). The WebUI uses this when enrolling a RADIUS token to populate the server-selection dropdown.

Requires the enrollment policy action enrollRADIUS.

Status Codes:

  • 200 OK – list of RADIUS-server identifiers in result.value.

GET /system/names/caconnector

Return the configured CA connectors with their templates but without their connection configuration (no secrets are included). The WebUI uses this when enrolling a certificate token to populate the CA-selection dropdown and the per-CA template list.

Requires the enrollment policy action enrollCERTIFICATE.

Status Codes:

  • 200 OK – list of CA-connector dictionaries (name, type, templates) in result.value.

GET /system/nodes

Return the privacyIDEA nodes declared in the server configuration. Each entry carries the node name and uuid and is used by multi-node features (per-node periodic tasks, per-node resolver visibility, …).

Requires admin authentication.

Request Headers:

  • PI-Authorization – authentication token.

Status Codes:

  • 200 OK – list of {"name", "uuid"} dictionaries in result.value.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": [
      {"name": "node1", "uuid": "12345678-1234-1234-1234-1234567890ab"},
      {"name": "node2", "uuid": "12345678-4321-1234-1234-1234567890ac"}
    ]
  },
  "version": "privacyIDEA unknown"
}

Added in version 3.10: Return node information with names and UUIDs

DELETE /system/user-cache

Flush the user cache. The user cache speeds up repeated user-store lookups; flushing it forces the next lookups to hit the backing resolvers again. Useful after a resolver configuration change.

Requires admin authentication.

Request Headers:

  • PI-Authorization – authentication token.

Status Codes:

  • 200 OK – {"status": True, "deleted": <n>} in result.value, where n is the number of cache entries removed.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": {"status": true, "deleted": 42}
  },
  "version": "privacyIDEA unknown"
}