Users, groups and operators

All routes below are under <ADMIN_URL>/admin/<company>/api and follow the change rules in The admin console.

Accounts (role users)

• GET users?limit=&after= lists the company's accounts in id order, at most 100 a page (50 unless limit says), with next naming the cursor of the following page and no total. ?email=<address> instead finds the one account that exact address signs in with; GET users/<user> reads one.
• Every address in these answers is masked to its first character and domain (k***@acme.example). POST users/<user>/email/reveal with a reason shows one address whole, and is recorded before it is shown; when the record cannot be written, nothing is shown.
• The accounts each operator is shown are counted per hour, and the read that takes an operator to 1 000 in an hour is logged as operator_reads_high.

Opening an account

POST users with {"email", "reason"} opens an active account that signs in with that address and answers 201 with its id and the address masked; an address the company already has is refused as email_taken. The account has no password until its user enrols:

• POST users/<user>/enrolment with a reason answers 201 with an enrolment code valid for 72 hours, shown in that answer only and kept only as its digest. A new code replaces the earlier one.
• With "by_mail": true the code is never shown: it goes to the account's address as a link to <issuer>/login/enrol#code=<code> and the answer says "mailed": true, so nobody at the console learns it. Without a relay the request answers 503 mail_unavailable and issues nothing.
• A code is refused for an account that already has a password (already_enrolled) or is disabled (account_disabled).

Disabling an account

POST users/<user>/disable and .../enable move an account between active and disabled, each only from the other status. Disabling ends every session of the account, telling its clients through the back channel, revokes every refresh family, ends any console session of its own, and answers access_tokens_end_by, when its access tokens stop working. A disabled account cannot sign in. Enabling gives back only that: nothing ended comes back.

Groups (role users)

A group holds accounts, never another group, and carries roles your applications read from UserInfo under the groups scope.

• GET groups, GET groups/<group> with its roles, GET groups/<group>/members.
• POST groups with {"group", "description", "roles", "reason"} makes one (409 group_taken for an id in use). A group id and a role are 1 to 64 lowercase letters, digits, - and _.
• POST groups/<group>/roles replaces its roles; POST groups/<group>/members with {"user"} adds an account (409 too_many_groups past 100 groups for one account); POST groups/<group>/members/<user>/remove takes one out; POST groups/<group>/remove deletes the group with every membership.

Operators

Holding a role is what lets an operator give it.

• GET operators lists the current grants of the roles the viewer holds.
• POST operators/<user>/grants/<role> with {"reason", "valid_days"} grants a role to an active account of the company for valid_days, 90 unless given and at most 365; no grant made in the console is permanent. A grant to oneself is refused as self_grant.
• POST operators/<user>/grants/<role>/revoke takes it away; the console of an operator with no role left ends at their next request.

Every grant and revoke is on the company's audit trail.

Companies (role companies, system console only)

• GET <ADMIN_URL>/admin/system/api/companies lists them, at most 100 a page.
• POST there with {"id", "name", "reason"} creates a company, makes its database and its console's client, and serves its issuer at once (201). An id in use is refused as company_taken, except a company whose creation stopped before it was served, which the same request completes.
• POST .../companies/<id>/suspend and .../resume stop and restart serving a company's issuer, on this node at once and on the others at their next directory refresh. A suspended company answers 404 like a name that was never one; system is never suspended.

A new company's first operator comes from tessaridb-oauth bootstrap-operator --company <id> (see Running it).