Management API

Every answer is checked against the model shown here before it is sent, and no answer carries a member its model does not list. A member shown as any JSON is one whose shape belongs to somebody else, and says whose. .{key} is a key that is data, and [] an element of a list.

A refusal

Unless an operation below says otherwise, any status it does not list answers this:

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean    
status integer    
why string    

GET /admin-api/rbac

getAdminRoles

Who may use the admin console, and how the gate is set

The two roles — Admin Read and Admin Write — with every grant, the settings behind the gate, and who the CALLER is (you).

The roles are two ORDINARY GROUPS in the embedded LDAP directory (admin.readGroup, admin.writeGroup), not a store of the console’s own. So this resource, /admin/rbac, an ldapmodify on 389 or 636 and a SCIM PATCH of the group are four doors onto one membership, and a grant made through any of them is visible through all of them.

WRITE IMPLIES READ. A member of the write group does not also need the read group.

The bootstrap administrator (admin.bootstrapUsername, reported in bootstrap) is made a member of both groups at startup. In DEVELOPMENT mode, until it first signs in to /admin (bootstrap.claimedAt), openToAnyone is true and anybody who signs in holds both roles; a process that never seeded it (bootstrap.seeded false) keeps the older rule: open while NEITHER group has a member. In PRODUCT mode the window never opens (windowOpens false, openToAnyone false whatever admin.openWhenEmpty says), and until the bootstrap administrator has claimed the console (bootstrapPasswordRequired true) its roles are honoured only from a PASSWORD sign-in through its own realm, which is also the only sign-in that claims it — a federation partner, a certificate, a wallet or a Kerberos ticket naming it holds nothing. admin.openWhenEmpty turns the open window off, and closedToEveryone reports a console no browser can reach, which is what this resource is the way out of.

enforced reports whether the roster decides anything. It is always true now — the console gate became unconditional on 2026-09-06 — and the field is kept because a client reading it should not have to know that.

EVERY LIST IN THE REPLY IS PAGED. grants by page and per, with page, pages, perPage, firstRow, lastRow and matched at the top level; candidates by candidatesPage and the same per, answered in candidatesPaging. roles carries each role’s counts (memberCount, presentCount, danglingCount, claimedCount) and, since 2026-09-13, not its members and claimed lists: those were every membership unpaged, and they are the rows grants pages — ?role=read narrows it to one role.

Mirrors GET /admin/rbac on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
q query string   Substring of the person’s name or of the raw membership value, case-insensitive.
role query one of read, write, security   Only grants of this role.
personq query string   Narrows candidates — the people a role could be granted to — to usernames containing this, case-insensitive. Where the directory is held in memory the list is the directory and who has signed in; where it is a window (#359) it is the direct children of ou=users, a page at a time, and a person who has signed in with no entry is not listed (a typed name can still be granted). candidateSearch says how many candidates there are in all and how many matched. A windowed search’s count stops at countCap (100,000, the furthest the pager reaches; #1308): where more match, matched is countCap and countCapped is true — MORE THAN matched match, and candidatesPaging stops there. Held in memory, the count is exact and countCapped is false. complete says whether this page holds every one it counted: where it is false, incomplete says how many names a DN cannot hold were left out (unusable), how many counted rows the page did not reach (short, most often two entries sharing one RDN value), and whether the list stops at the walk’s cap (capped, cap).
candidatesPage query integer   Which page of the matching candidates, answered in candidatesPaging. Clamped like page. The page size is per when given — shared with grants, as on every reply here carrying two lists — and otherwise twenty, the size of the console’s results pane. candidates was the whole list until 2026-09-13, which on a directory of thousands was thousands of rows on every read of the roster.
personfrom query integer   The console results pane’s OFFSET into the matching candidates, answered as the page it falls on. Ignored when candidatesPage is given, and when it is past the end.
person query string   A username to look up among ALL the candidates, not only the page shown. picked.candidate is its row, or null when nobody by that name could be picked.
page query integer   Which page of the match to return. CLAMPED rather than refused: a page past the end returns the last one, and the reply says which page it actually is.
per query integer   Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The roster, the settings, and who is asking.

Member Type Required What it is
available boolean    
bootstrap object    
bootstrap.claimedAt string, or null    
bootstrap.seeded boolean    
bootstrap.username string, or null    
bootstrapPasswordRequired boolean    
candidatePane object    
candidatePane.countCapped boolean    
candidatePane.from number    
candidatePane.matched number    
candidatePane.shown list    
candidatePane.shown[].inDirectory boolean    
candidatePane.shown[].seen boolean    
candidatePane.shown[].username string    
candidateSearch object    
candidateSearch.complete boolean    
candidateSearch.countCap number    
candidateSearch.countCapped boolean    
candidateSearch.incomplete object    
candidateSearch.incomplete.cap number    
candidateSearch.incomplete.capped boolean    
candidateSearch.incomplete.short number    
candidateSearch.incomplete.unusable number    
candidateSearch.matched number    
candidateSearch.q string, or null    
candidateSearch.total number    
candidates list    
candidates[].inDirectory boolean    
candidates[].seen boolean    
candidates[].username string    
candidatesPaging object    
candidatesPaging.firstRow integer    
candidatesPaging.lastRow integer    
candidatesPaging.noun string    
candidatesPaging.page integer    
candidatesPaging.pages integer    
candidatesPaging.param string    
candidatesPaging.perPage integer    
candidatesPaging.total integer    
closedToEveryone boolean    
enforced boolean    
filter object    
filter.q string, or null    
filter.role string, or null    
firstRow integer    
grantCount number    
grants list    
grants[].attribute string    
grants[].cn string    
grants[].dn string    
grants[].holds string    
grants[].kind string    
grants[].memberDn string    
grants[].present boolean    
grants[].role string    
grants[].roleLabel string    
grants[].userKey string    
grants[].username string    
grants[].value string    
groupsDn string    
known map    
known.{key} boolean    
lastRow integer    
matched number    
openToAnyone boolean    
openWhenEmpty boolean    
page integer    
pages integer    
paging object    
paging.firstRow integer    
paging.lastRow integer    
paging.noun string    
paging.page integer    
paging.pages integer    
paging.param string    
paging.perPage integer    
paging.total integer    
perPage integer    
picked object    
picked.asked string    
picked.candidate object    
picked.candidate.inDirectory boolean    
picked.candidate.seen boolean    
picked.candidate.username string    
roleChoices list    
roleChoices[].id string    
roleChoices[].implies list    
roleChoices[].implies[] string    
roleChoices[].label string    
roleChoices[].setting string    
roleChoices[].what string    
roles list    
roles[].claimedCount number    
roles[].cn string    
roles[].createdAt string, or number, or null    
roles[].danglingCount number    
roles[].dn string    
roles[].exists boolean    
roles[].implies list    
roles[].implies[] string    
roles[].label string    
roles[].memberCount number    
roles[].modifiedAt string, or number, or null    
roles[].origin string    
roles[].presentCount number    
roles[].role string    
roles[].what string    
settings object    
settings.context object    
settings.context.configFile string, or null    
settings.context.defaultsFile string, or null    
settings.context.inRealm boolean    
settings.context.persistenceMode string    
settings.context.persistsAppconfig boolean    
settings.context.persistsRealms boolean    
settings.context.realmId string    
settings.editableCount integer    
settings.groups list    
settings.groups[].group string    
settings.groups[].settings list    
settings.groups[].settings[].appconfigPath string    
settings.groups[].settings[].csvValueNotes map    
settings.groups[].settings[].csvValueNotes.{key} string    
settings.groups[].settings[].csvValues list    
settings.groups[].settings[].csvValues[] string, or number, or boolean, or null    
settings.groups[].settings[].default list, or string, or number, or boolean, or null    
settings.groups[].settings[].default[] string, or number, or boolean, or null    
settings.groups[].settings[].description string    
settings.groups[].settings[].editRefusal string    
settings.groups[].settings[].editable boolean    
settings.groups[].settings[].enumValues list    
settings.groups[].settings[].enumValues[] string, or number, or boolean, or null    
settings.groups[].settings[].env list, or string    
settings.groups[].settings[].env[] string    
settings.groups[].settings[].group string    
settings.groups[].settings[].key string    
settings.groups[].settings[].label string    
settings.groups[].settings[].legacyEnv list, or string    
settings.groups[].settings[].legacyEnv[] string    
settings.groups[].settings[].masked boolean    
settings.groups[].settings[].max number    
settings.groups[].settings[].min number    
settings.groups[].settings[].ordered boolean    
settings.groups[].settings[].overridden boolean    
settings.groups[].settings[].realmSettable boolean    
settings.groups[].settings[].restartReason string    
settings.groups[].settings[].selectAll object    
settings.groups[].settings[].selectAll.aloneWhileOn list    
settings.groups[].settings[].selectAll.aloneWhileOn[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.aloneWhileOn[].values object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn list    
settings.groups[].settings[].selectAll.onlyWhileOn[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.onlyWhileOn[].values object   Nested deeper than this page draws.
settings.groups[].settings[].source string    
settings.groups[].settings[].step number    
settings.groups[].settings[].text string, or null    
settings.groups[].settings[].type string    
settings.groups[].settings[].value list, or string, or number, or boolean, or null    
settings.groups[].settings[].value[] string, or number, or boolean, or null    
settings.overridden list    
settings.overridden[] string    
settings.page string    
settings.setWith string    
settings.settingCount integer    
settings.sharedWith map    
settings.sharedWith.{key} list    
settings.sharedWith.{key}[] object, or string    
settings.sharedWith.{key}[].label string    
settings.sharedWith.{key}[].path string    
shown number    
usersDn string    
windowOpens boolean    
you object    
you.read boolean    
you.roles list    
you.roles[] string    
you.username string, or null    
you.viaEmptyRoster boolean    
you.write boolean    

400: The answer.

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean yes  

POST /admin-api/rbac/grant

grantAdminRole

Give somebody a console role

Adds them to the role’s group as a member, creating the group if this is the first grant — which is why “the group does not exist” and “the group has no members” are the same state everywhere in this feature.

The person must exist. A name with no entry in this realm’s directory is REFUSED with 400, reason: "noSuchPerson" and an errors sentence naming them, and nothing is written: create them first (POST /admin-api/users/create) and grant the role then. A role is granted only to somebody who exists, so that a person created later under the same name inherits nothing. A name carrying a character RFC 4514 reserves in a DN is refused too — the same refusal POST /admin-api/users/create gives, for the same reason.

Granting a role somebody already holds answers 200 with changed: false rather than 400, so a script that grants on every run does not fail on its second one.

THE FIRST GRANT ON A SERVICE CLOSES THE DOOR BEHIND IT. While the roster is empty anybody who signs in holds both roles; the moment one grant exists, everybody not in one of the two groups is refused at every page of the console. Grant yourself first.

Mirrors POST /admin/rbac on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
role one of read, write, security yes write includes read.
username string yes The name they sign in as — the same string that appears in a token’s sub and on /admin/users.

200: What was granted, and where the membership was written. changed: false means they already held it.

Member Type Required What it is
changed boolean    
created boolean    
dn string    
entry object    
entry.attributes map    
entry.attributes.{key} list, or string    
entry.attributes.{key}[] string    
entry.createdAt string, or number, or null    
entry.dn string    
entry.members list    
entry.members[].attribute string    
entry.members[].cn string    
entry.members[].displayName string    
entry.members[].dn string    
entry.members[].holds string    
entry.members[].kind string    
entry.members[].mail string    
entry.members[].present boolean    
entry.members[].userKey string    
entry.members[].value string    
entry.modifiedAt string, or number, or null    
entry.operational list    
entry.operational[] string    
entry.origin string    
entry.rule string    
errors list    
errors[] string    
member string    
message string    
ok boolean yes  
problems list    
problems[] map, or string    
problems[].{key} string, or number, or boolean, or null    
reason string    
resolves boolean    
role string    
username string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
changed boolean    
created boolean    
dn string    
entry object    
entry.attributes map    
entry.attributes.{key} list, or string    
entry.attributes.{key}[] string    
entry.createdAt string, or number, or null    
entry.dn string    
entry.members list    
entry.members[].attribute string    
entry.members[].cn string    
entry.members[].displayName string    
entry.members[].dn string    
entry.members[].holds string    
entry.members[].kind string    
entry.members[].mail string    
entry.members[].present boolean    
entry.members[].userKey string    
entry.members[].value string    
entry.modifiedAt string, or number, or null    
entry.operational list    
entry.operational[] string    
entry.origin string    
entry.rule string    
errors list    
errors[] string    
member string    
message string    
ok boolean yes  
problems list    
problems[] map, or string    
problems[].{key} string, or number, or boolean, or null    
reason string    
resolves boolean    
role string    
username string    

POST /admin-api/rbac/revoke

revokeAdminRole

Take a console role away

Removes them from the role’s group — from EVERY membership attribute that named them (member, uniqueMember, memberUid) rather than from the first one found, because a person listed twice by two clients would otherwise still hold the role after a revoke that reported success.

Revoking a role somebody does not hold answers 200 with changed: false, and so does revoking from a group that does not exist.

Taking away the LAST grant empties the roster. Where no bootstrap administrator was seeded that re-opens the console to anybody who signs in, in development mode (or closes it to everybody, if admin.openWhenEmpty is off, and always in product mode); once the bootstrap administrator has signed in it closes the console to everybody. The reply says which.

Mirrors POST /admin/rbac on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
role one of read, write, security yes  
username string yes Who to take it from.

200: What was removed, and whether the roster is now empty.

Member Type Required What it is
changed boolean    
dn string    
errors list    
errors[] string    
message string    
ok boolean yes  
problems list    
problems[] map, or string    
problems[].{key} string, or number, or boolean, or null    
reason string    
removed number    
role string    
username string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
changed boolean    
dn string    
errors list    
errors[] string    
message string    
ok boolean yes  
problems list    
problems[] map, or string    
problems[].{key} string, or number, or boolean, or null    
reason string    
removed number    
role string    
username string