16.1.1.9. Default Realm endpoints¶

These endpoints are used to define the default realm, retrieve it and delete it.

POST /defaultrealm/(realm)¶

Set the default realm. The previous default (if any) is cleared in the same transaction.

Requires admin authentication and the policy action resolverwrite, resolverread, resolverdelete.

Parameters:

realm – path component, the name of the realm to make the default. Lower-cased and stripped before lookup.

Request Headers:

PI-Authorization – authentication token.

Status Codes:

200 OK – database id of the new default realm in result.value.
404 Not Found – no realm with the given name exists.

Example request:

POST /defaultrealm/new_default_realm HTTP/1.1
Host: example.com

Example response:

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

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

DELETE /defaultrealm¶

Clear the default realm. The realm definitions themselves are not touched; only the default flag is removed from whichever realm currently carries it. After this call, requests that omit the realm parameter will no longer resolve a default and must specify realm explicitly.

Requires admin authentication and the policy action resolverwrite, resolverread, resolverdelete.

Request Headers:

PI-Authorization – authentication token.

Status Codes:

200 OK – database id of the realm that was the default in result.value, or 0 if no default was set.

Example request:

DELETE /defaultrealm HTTP/1.1
Host: example.com

Example response:

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

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

GET /defaultrealm¶

Return the default realm with its resolver list. If no realm is currently flagged as default, the response value is an empty dictionary.

Requires admin authentication.

Request Headers:

PI-Authorization – authentication token.

Status Codes:

200 OK – single-entry dict keyed by the default-realm name, or {} when no default is set.

Example response:

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": {
      "defrealm": {
        "default": true,
        "id": 1,
        "resolver": [
          {
            "name": "defresolver",
            "node": "",
            "priority": null,
            "type": "passwdresolver"
          }
        ]
      }
    }
  },
  "version": "privacyIDEA unknown"
}