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 |