16.1.1.2. Authentication endpoints

The auth REST API issues the JWT-based authentication tokens that every other administrative or user-self endpoint expects. Four authentication paths are supported:

  • Password — username and password verified against the local admin database, then against the user store. Token authentication may be required on top by the WebUI login_mode policy.

  • FIDO2 / Passkey — credential_id plus transaction_id from a prior call to POST /validate/initialize.

  • REMOTE_USER — when an upstream web server (Apache, nginx) has already authenticated the request, REMOTE_USER is honored if the WebUI remote_user policy is active.

  • Trusted JWT — JWTs signed by an external IdP are accepted on any authenticated endpoint when the IdP’s public key, algorithm and a username regex are listed in PI_TRUSTED_JWT.

A successful login returns a JWT carrying username, realm, role (user or admin), rights (the policy-derived list of allowed actions), authtype (password / pi / remote_user) and an exp claim. The default validity is one hour; the WebUI jwt_validity policy overrides it.

Subsequent requests carry the token in the PI-Authorization header (Authorization is also accepted as a fallback). Calls that require authentication return a 401 response if the token is absent, malformed or expired.

This API is distinct from Validate endpoints, which checks OTP values for end users.

POST /auth

Verify credentials and issue a JWT authentication token.

Four credential shapes are accepted, see the module-level description for the full picture:

  • password (username + password);

  • passkey / FIDO2 (credential_id + transaction_id);

  • REMOTE_USER, when allowed by the WebUI remote_user policy;

  • a trusted external JWT, when configured via PI_TRUSTED_JWT.

The returned JWT carries username, realm, role (user or admin), rights, authtype and exp. The default validity is one hour; this is overridable per user/realm via the WebUI jwt_validity policy. The WebUI also reads log_level and menus from the response to render the right chrome.

Several policy actions affect this endpoint, including login_mode (whether token auth is required on top of password), policy_remote_user (whether REMOTE_USER is honored) and the FIDO2/passkey, push, WebAuthn and time-limit policies enforced by the registered prepolicies.

Multi-step (challenge-response) login: when the user is configured with a challenge-response token type, the first call returns a 200 with result.value=False and detail.multi_challenge listing the active challenges. The caller submits the OTP via a second POST /auth call carrying the same fields plus transaction_id.

JSON Parameters:

  • username – login name (required for password / REMOTE_USER flows).

  • password – password / credentials (required for password flow).

  • realm – optional realm to scope the user lookup; defaults to the realm in username@realm syntax, otherwise the default realm.

  • credential_id – FIDO2 credential id (required for passkey flow).

  • transaction_id – transaction id from a prior POST /validate/initialize (required for passkey and for the second leg of a challenge-response flow).

Status Codes:

  • 200 OK – success — the JWT is in result.value.token; or first leg of a challenge-response — result.value is False and detail.multi_challenge describes the next step.

  • 401 Unauthorized – authentication failed (wrong or missing credentials, unknown realm, expired token).

Example request:

POST /auth HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

username=admin&password=topsecret

Example response:

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": {
      "token": "eyJhbGciOiJIUz....jdpn9kIjuGRnGejmbFbM",
      "role": "admin",
      "username": "admin",
      "realm": "",
      "log_level": 30,
      "rights": ["enrollHOTP", "enrollTOTP", ...],
      "menus": ["tokens", "users", ...],
      "auth": true
    }
  },
  "version": "privacyIDEA unknown"
}
GET /auth/rights

Return the token types the logged-in principal is allowed to enroll, computed from the active enrollment policies and the request’s IP, user-agent and identity. The WebUI calls this immediately after login to render the enrollment UI.

Requires authentication (any role).

Request Headers:

  • PI-Authorization – JWT auth token returned by POST /auth. Authorization is accepted as a fallback.

Status Codes:

  • 200 OK – list of allowed enrollment token types in result.value.

Example Request:

Requests to privacyidea then should use this security token in the Authorization field in the header.

GET /users/ HTTP/1.1
Host: example.com
Accept: application/json
Authorization: eyJhbGciOiJIUz....jdpn9kIjuGRnGejmbFbM