16.1.1.8. Realm endpoints¶

The realm REST API manages realms. A realm composes one or more User ID Resolvers into a single user space; tokens and policies are scoped against realms, and only users that belong to a realm are visible to privacyIDEA. The same blueprint also exposes the /defaultrealm endpoints that read, set and clear which realm new users are looked up in when no realm is supplied explicitly.

All endpoints require admin authentication. Listing realms is allowed for any admin but the response is filtered by the calling admin’s policy match — realm-admins only see realms their policies cover. Create / update / delete are gated by resolverwrite, resolverread, resolverdelete and resolverwrite, resolverread, resolverdelete.

POST /realm/(realm)¶

Create or reconfigure a realm. The realm is defined as a list of resolvers, optionally with a per-resolver priority used to disambiguate when the same login name resolves in more than one resolver. Resolvers attached to specific nodes are preserved across this call (use POST /realm/(realm)/node/(nodeid) to manage them).

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

Parameters:

realm – path component, the unique name of the realm.

JSON Parameters:

resolvers – comma-separated string or JSON list of resolver names that should make up this realm (required).
priority.<resolvername> – integer priority for the named resolver (optional).

Request Headers:

PI-Authorization – authentication token.

Status Codes:

200 OK – {"added": [...], "failed": [...]} in result.value.

Example request:

POST /realm/newrealm HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "resolvers": "reso1_with_realm,reso2_with_realm",
  "priority.reso1_with_realm": 1,
  "priority.reso2_with_realm": 2
}

Example response:

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": {
      "added": ["reso1_with_realm", "reso2_with_realm"],
      "failed": []
    }
  },
  "version": "privacyIDEA unknown"
}

GET /realm/¶

Return all realms visible to the calling admin. The response is a dictionary keyed by realm name; each entry carries the default flag and a list of resolver records with name, type, node and priority.

The result is filtered against the calling admin’s policy match — realm-admins only see realms their policies cover.

Requires admin authentication.

Request Headers:

PI-Authorization – authentication token.

Status Codes:

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

Example request:

GET /realm/ 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": {
      "realm1_with_resolver": {
        "default": true,
        "resolver": [
          {
            "name": "reso1_with_realm",
            "node": "",
            "priority": null,
            "type": "passwdresolver"
          }
        ]
      }
    }
  },
  "version": "privacyIDEA unknown"
}

Changed in version 3.10: The response contains the node and priority of the resolver

GET /realm/superuser¶

Return the list of superuser realms — the realms whose users are treated as administrators. The list is taken from the SUPERUSER_REALM setting in pi.cfg; see The Config File.

Requires admin authentication.

Request Headers:

PI-Authorization – authentication token.

Status Codes:

200 OK – list of superuser-realm names in result.value.

Example response:

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

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

DELETE /realm/(realm)¶

Delete a realm. The realm can only be deleted if no user from this realm is still attached to a token or a container.

If the deleted realm was the default realm and exactly one realm remains afterwards, that remaining realm is automatically promoted to default.

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

Parameters:

realm – path component, the name of the realm to delete.

Request Headers:

PI-Authorization – authentication token.

Status Codes:

200 OK – database id of the deleted realm in result.value.
400 Bad Request – a token or container in this realm still has a user assigned.
404 Not Found – no realm with the given name exists.

Example request:

DELETE /realm/realm_to_delete 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": 1
  },
  "version": "privacyIDEA unknown"
}

POST /realm/(string: realm)/node/(string: nodeid)¶

Create or reconfigure the resolver assignment for a realm on a specific privacyIDEA node. Resolvers attached to other nodes (and node-less resolvers in this realm) are preserved across the call; only the resolvers bound to nodeid are replaced.

The body must be JSON (Content-Type: application/json) and contain a resolver list of {name, priority} objects.

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

Parameters:

realm – path component, the unique name of the realm.
nodeid – path component, the UUID of the node.

Request Headers:

Content-Type – application/json (required).
PI-Authorization – authentication token.

Request JSON Object:

resolver (list) – list of objects, each with name (string, required) and priority (integer, optional).

Status Codes:

200 OK – {"added": [...], "failed": [...]} in result.value.
400 Bad Request – the node UUID is unknown, the body is missing the resolver key, or a resolver entry could not be parsed.

Example request:

Replace the resolvers of realm newrealm on the node with UUID 8e4272a9-9037-40df-8aa3-976e4a04b5a9 with resolver1 and resolver2:

POST /realm/newrealm/node/8e4272a9-9037-40df-8aa3-976e4a04b5a9 HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "resolver": [
    {"name": "resolver1", "priority": 1},
    {"name": "resolver2", "priority": 2}
  ]
}

Example response:

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": {
      "added": ["resolver1", "resolver2"],
      "failed": []
    }
  },
  "version": "privacyIDEA unknown"
}

Added in version 3.10: Node specific realm configuration