privacyIDEA

https://privacyidea.readthedocs.io/en/stable/
Admin
privacyIDEA is an open-source authentication system that provides multi-factor authentication (MFA)...
Tokens:1,167,716
Snippets:7,383
Trust Score:9.6
Update:1 week ago
Show doc for...
Tokens:
Raw
### GET /healthz/startupz - Example Response

Source: https://privacyidea.readthedocs.io/en/stable/modules/api/healthcheck.html

HTTP response from the startup check endpoint. Shows a 200 OK with a JSON body indicating the application has started.

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

{
    "status": "started"
}

```

--------------------------------

### GET /system/<key> example request

Source: https://privacyidea.readthedocs.io/en/stable/modules/api/system.html

Example HTTP request to retrieve a single configuration entry by key, here 'totp.hashlib'.

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

```

--------------------------------

### GET /healthz/startupz - Example Request

Source: https://privacyidea.readthedocs.io/en/stable/modules/api/healthcheck.html

HTTP request to the startup check endpoint. Returns 200 with status 'started' when the app has started, or 503 with 'not started' otherwise.

```http
GET /healthz/startupz HTTP/1.1
Host: example.com
Accept: application/json

```

--------------------------------

### GET /system/<key> example response

Source: https://privacyidea.readthedocs.io/en/stable/modules/api/system.html

Example HTTP response showing the value of a single configuration key in result.value.

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

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

```

--------------------------------

### GET /system/ example request

Source: https://privacyidea.readthedocs.io/en/stable/modules/api/system.html

Example HTTP request to retrieve all system configuration entries. Requires admin authentication or authenticated user with configread policy.

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

```

--------------------------------

### GET /system/ example response

Source: https://privacyidea.readthedocs.io/en/stable/modules/api/system.html

Example HTTP response showing a dictionary of configuration entries in result.value.

```http
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"
}

```

--------------------------------

### GET /user/ example request

Source: https://privacyidea.readthedocs.io/en/stable/modules/api/user.html

Example HTTP request to list users in a realm. Uses the realm query parameter.

```http
GET /user/?realm=realm1 HTTP/1.1
Host: example.com
Accept: application/json

```

--------------------------------

### GET /machine/ example response

Source: https://privacyidea.readthedocs.io/en/stable/modules/api/machines.html

Example response for listing machines. Returns a list of machine dictionaries in result.value with status 200 OK.

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": [
      {
        "id": "908asljdas90ad0",
        "hostname": ["flavon.example.com", "test.example.com"],
        "ip": "1.2.3.4",
        "resolver_name": "machineresolver1"
      },
      {
        "id": "1908209x48x2183",
        "hostname": ["london.example.com"],
        "ip": "2.4.5.6",
        "resolver_name": "machineresolver1"
      }
    ]
  },
  "version": "privacyIDEA unknown"
}

```

--------------------------------

### GET /healthz/readyz - Example Request

Source: https://privacyidea.readthedocs.io/en/stable/modules/api/healthcheck.html

HTTP request to the readiness check endpoint. Returns 200 when the app is ready and the HSM is ready, or 503 otherwise.

```http
GET /healthz/readyz HTTP/1.1
Host: example.com
Accept: application/json

```

--------------------------------

### Example /etc/cron.d/privacyidea for PyPI installation

Source: https://privacyidea.readthedocs.io/en/stable/installation/system/cleanupjobs.html

Create this cron file for PyPI installations to schedule cleanup jobs. Adjust the paths to your virtual environment and set PRIVACYIDEA_CONFIGFILE if your config is not /etc/privacyidea/pi.cfg. The audit and authentication log jobs are not included; add them with your chosen retention period.

```cron
*/5 * * * *  privacyidea  /opt/privacyidea/bin/privacyidea-cron run_scheduled -c
0 1 * * *    privacyidea  /opt/privacyidea/bin/pi-manage config challenge cleanup > /dev/null
10 1 * * *   privacyidea  /opt/privacyidea/bin/pi-manage config remembered_device cleanup > /dev/null
20 1 * * *   privacyidea  /opt/privacyidea/bin/pi-manage config authcache cleanup > /dev/null
30 1 * * *   privacyidea  /opt/privacyidea/bin/pi-manage config metrics cleanup > /dev/null
40 1 * * *   privacyidea  /opt/privacyidea/bin/pi-manage conditionalaccess purge-expired-blocks > /dev/null
40 1 * * *   privacyidea  /opt/privacyidea/bin/pi-manage conditionalaccess purge-expired-locks > /dev/null
50 1 * * *   privacyidea  /opt/privacyidea/bin/privacyidea-usercache-cleanup > /dev/null

```

--------------------------------

### GET /user/ example response

Source: https://privacyidea.readthedocs.io/en/stable/modules/api/user.html

Example JSON response for the GET /user/ endpoint, showing a user object with attributes.

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": [
      {
        "username": "alice",
        "userid": "1009",
        "givenname": "Alice",
        "surname": "Liddell",
        "email": "alice@example.com",
        "mobile": "+44 12345",
        "phone": "+44 67890",
        "description": "Alice Liddell,...",
        "realm": "realm1",
        "resolver": "ldap-corp",
        "editable": false
      }
    ]
  },
  "version": "privacyIDEA unknown"
}

```

--------------------------------

### Enable and configure services

Source: https://privacyidea.readthedocs.io/en/stable/installation/centos.html

Enables and starts the HTTP and MariaDB services, then runs the mysql_secure_installation script to secure the database.

```bash
$ systemctl enable --now httpd
$ systemctl enable --now mariadb
$ mysql_secure_installation

```

--------------------------------

### GET /application/ request

Source: https://privacyidea.readthedocs.io/en/stable/modules/api/application.html

Example HTTP request to the GET /application/ endpoint. Requires admin authentication.

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

```

--------------------------------

### Example configuration options in pi.cfg

Source: https://privacyidea.readthedocs.io/en/stable/installation/system/inifile.html

Shows commented configuration options that can be set in the pi.cfg file, which is parsed as Python code. Includes database, logging, and UI settings.

```python
# PI_AUDIT_MODULE = <python audit module>
# PI_AUDIT_SQL_URI = <special audit log DB uri>
# Options passed to the Audit DB engine (supersedes SQLALCHEMY_ENGINE_OPTIONS)
# PI_AUDIT_SQL_OPTIONS = {}
# PI_LOGFILE = '....'
# PI_LOGLEVEL = 20
# PI_INIT_CHECK_HOOK = 'your.module.function'
# PI_CSS = '/location/of/theme.css'
# PI_UI_DEACTIVATED = True
# PI_ENABLE_CSP = True
# PI_FORCE_HTTPS = True
```

--------------------------------

### Create a backup with pi-manage backup create

Source: https://privacyidea.readthedocs.io/en/stable/installation/system/pi-manage.html

Creates an archive with a dump of the privacyIDEA database and the configuration directory /etc/privacyidea to /var/lib/privacyidea/backup/privacyidea-backup-<YYYYMMDD-HHMM>.tgz. Options include -e/--enckey to add the encryption key, -d to change the output directory, -c to back up another configuration directory, and -r to add a FreeRADIUS configuration directory.

```bash
pi-manage backup create

```

--------------------------------

### POST /token/init (Step 1: Initiate WebAuthn Enrollment)

Source: https://privacyidea.readthedocs.io/en/stable/_modules/privacyidea/lib/tokens/webauthntoken.html

Initiates WebAuthn token enrollment by sending a POST request to /token/init with type=webauthn and the username. The response contains a webAuthnRegisterRequest with the challenge data needed for the client-side WebAuthn API.

```APIDOC
## POST /token/init

### Description
Initiates WebAuthn token enrollment. Returns a webAuthnRegisterRequest containing the challenge, relying party information, and other parameters required for the WebAuthn client-side API.

### Method
POST

### Endpoint
/token/init

### Parameters
#### Request Body
- **type** (string) - Required - Must be set to `webauthn`.
- **user** (string) - Required - The username for which the token is being enrolled.

### Request Example
```http
POST /token/init HTTP/1.1
Host: <privacyIDEA server>
Accept: application/json

type=webauthn
user=<username>
```

### Response
#### Success Response (200)
- **detail.serial** (string) - The serial number of the new token.
- **detail.webAuthnRegisterRequest** (object) - Contains the registration challenge data.
  - **attestation** (string) - Attestation type (e.g., "direct").
  - **authenticatorSelection** (object) - Authenticator selection criteria.
  - **displayName** (string) - Display name for the user.
  - **message** (string) - Message to display to the user.
  - **name** (string) - Username.
  - **nonce** (string) - Challenge nonce (web-safe base64).
  - **pubKeyCredAlgorithms** (array) - List of supported public key algorithms.
  - **relyingParty** (object) - Relying party information (id and name).
  - **serialNumber** (string) - Serial number of the token.
  - **timeout** (integer) - Timeout in milliseconds.
  - **transaction_id** (string) - Transaction ID for the enrollment process.
- **result.status** (boolean) - Indicates success.
- **result.value** (boolean) - Indicates success.
- **version** (string) - privacyIDEA version.

#### Response Example
```json
{
    "detail": {
        "serial": "<serial number>",
        "webAuthnRegisterRequest": {
            "attestation": "direct",
            "authenticatorSelection": {
                "userVerification": "preferred"
            },
            "displayName": "<user.resolver@realm>",
            "message": "Please confirm with your WebAuthn token",
            "name": "<username>",
            "nonce": "<nonce>",
            "pubKeyCredAlgorithms": [
                {
                    "alg": -7,
                    "type": "public-key"
                },
                {
                    "alg": -37,
                    "type": "public-key"
                }
            ],
            "relyingParty": {
                "id": "<relying party ID>",
                "name": "<relying party name>"
            },
            "serialNumber": "<serial number>",
            "timeout": 60000,
            "transaction_id": "<transaction ID>"
        }
    },
    "result": {
        "status": true,
        "value": true
    },
    "version": "<privacyIDEA version>"
}
```
```

--------------------------------

### POST /system/setConfig example response

Source: https://privacyidea.readthedocs.io/en/stable/modules/api/system.html

Example HTTP response showing the result of setting configuration entries, with each key mapped to 'insert' or 'update'.

```http
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"
}

```

--------------------------------

### GET /serviceid/ - Example response

Source: https://privacyidea.readthedocs.io/en/stable/modules/api/serviceid.html

Response to a successful GET request. Returns a dictionary keyed by service ID name, each value carrying description and id.

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": {
      "service1": {"description": "1st service", "id": 1},
      "service2": {"description": "2nd service", "id": 2}
    }
  },
  "version": "privacyIDEA unknown"
}
```

--------------------------------

### GET /validate/capabilities example response

Source: https://privacyidea.readthedocs.io/en/stable/modules/api/validate.html

Example HTTP response from the capabilities discovery endpoint. Returns capabilities in result.value, with remember_device indicating a policy exists for the server, not a per-user guarantee.

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

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

```

--------------------------------

### Start development server with pi-manage

Source: https://privacyidea.readthedocs.io/en/stable/installation/pip.html

Command to start the development server. Note: not for production use. In versions before 3.10, use 'runserver' instead.

```bash
(privacyidea)$ pi-manage run

```

--------------------------------

### POST /system/setConfig example request

Source: https://privacyidea.readthedocs.io/en/stable/modules/api/system.html

Example HTTP request to set system configuration entries. The body is a flat dictionary of key-value pairs, with optional type and description companion keys.

```http
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"
}

```

--------------------------------

### GET /audit/audit.csv example request

Source: https://privacyidea.readthedocs.io/en/stable/modules/api/audit.html

Example HTTP request to download the audit log as a CSV file, filtering by realm. Requires admin authentication and the auditlog_download policy action.

```http
GET /audit/audit.csv?realm=realm1 HTTP/1.1
Host: example.com
Accept: text/csv

```

--------------------------------

### init_registration(server_url, scope, registration_ttl, ssl_verify, params=None)

Source: https://privacyidea.readthedocs.io/en/stable/modules/lib/containertypes/smartphone.html

Initializes the registration by generating a QR code containing all relevant data. Returns a dictionary with registration data including container URL, nonce, timestamp, key algorithm, hash algorithm, SSL verify flag, TTL, and optional passphrase.

```APIDOC
## init_registration(server_url, scope, registration_ttl, ssl_verify, params=None)

### Description
Initializes the registration: Generates a QR code containing all relevant data.

### Method
Class method

### Endpoint
N/A (SDK method)

### Parameters
- **server_url** (str) - Required - URL of the server reachable for the client.
- **scope** (str) - Required - The URL the client contacts to finalize the registration e.g. "https://pi.net/container/register/finalize".
- **registration_ttl** (int) - Required - Time to live of the registration link in minutes.
- **ssl_verify** (bool) - Required - Whether the client shall use ssl.
- **params** (dict) - Optional - Container specific parameters in the format:
```
{
    "passphrase_prompt": <str, the prompt for the passphrase displayed in the app>, (optional)
    "passphrase_response": <str, passphrase>, (optional)
    "passphrase_user": <bool, whether the passphrase shall be validated against the user store>, (optional)
    "extra_data": <dict, any additional data>, (optional)
}
```

### Returns
A dictionary with the registration data. An example of a returned dictionary:
```
{
    "container_url": {
        "description": "URL for privacyIDEA Container Registration",
        "value": <url>,
        "img": <qr code of the url>
    },
    "nonce": "ajhbdsuiuojno49877n4no3u09on38r98n",
    "time_stamp": "2020-08-25T14:00:00.000000+00:00",
    "key_algorithm": "secp384r1",
    "hash_algorithm": "SHA256",
    "ssl_verify": "True",
    "ttl": 10,
    "passphrase": <Passphrase prompt displayed to the user in the app> (optional)
}
```
```

--------------------------------

### GET /client/ request

Source: https://privacyidea.readthedocs.io/en/stable/modules/api/client.html

Example HTTP request to retrieve all client applications that have authenticated against privacyIDEA.

```http
GET /client/ HTTP/1.1
Host: example.com
Accept: application/json
```

--------------------------------

### Setup privacyIDEA with pi-manage

Source: https://privacyidea.readthedocs.io/en/stable/installation/centos.html

Uses the pi-manage tool to create the encryption key, audit keys, and database tables.

```bash
(privacyidea)$ pi-manage setup create_enckey  # encryption key for the database
(privacyidea)$ pi-manage setup create_audit_keys  # key for verification of audit log entries
(privacyidea)$ pi-manage setup create_tables  # create the database structure

```

--------------------------------

### tokeninfo policy example: last_auth/^2018.*/

Source: https://privacyidea.readthedocs.io/en/stable/policies/authorization.html

Example of a 'tokeninfo' policy action that requires the tokeninfo field to start with '2018'. This is checked after authentication, so a valid OTP value is used up even if the user is not authorized.

```plaintext
action = last_auth/^2018.*/
```

--------------------------------

### POST /token/init

Source: https://privacyidea.readthedocs.io/en/stable/modules/lib/tokentypes/tiqr.html

Starts the enrollment of a TiQR token. No otpkey is required as it is generated on the smartphone and pushed to the server in a subsequent step.

```APIDOC
## POST /token/init

### Description
Starts the enrollment of a TiQR token. The response contains a QR code in the details that the user scans with the TiQR app.

### Method
POST

### Endpoint
/token/init

### Parameters
#### Request Body
- **type** (string) - Required - Must be set to "tiqr" to enroll a TiQR token.
- **user** (string) - Required - The username for which the token is enrolled.
- **realm** (string) - Optional - The realm of the user.

### Response
#### Success Response (200)
- **result** (object) - Contains the enrollment status.
- **detail** (object) - Contains the QR code value in the `qr` field.

#### Response Example
{
  "result": {
    "status": true,
    "value": true
  },
  "detail": {
    "qr": "otpauth://tiqr?action=metadata&..."
  }
}
```
Tokens:
Raw