Manage accounts
Every person and machine identity in Facet is an account document of doctype
iam.Account. You create accounts, send the first credential, and control the
status of each one. Accounts follow the same event-sourced document rules as
any other record, so every change is audited and reversible.
When to use this
Section titled “When to use this”- You add a new member or a machine identity.
- A member has no password, or forgot it before signing in once.
- You must stop an account from signing in, or bring a deleted account back.
Before you start
Section titled “Before you start”- The right page. Open Configure → Access → Accounts. You need a role
that grants
updateoniam.Accountto create or edit accounts. - The credential right. To send credentials you also need the named action
provision_credentialsoniam.Account. The seedediam.Roles.adminrole holds it through its*on*.*line. - The model. Read Roles and permission lines to learn how named actions work.
The account document
Section titled “The account document”| Field | Holds |
|---|---|
email |
The sign-in identifier. Unique among live accounts. |
name |
The display name. |
status |
pending, active, suspended, or disabled. |
roles |
The assigned roles, as qualified ids such as iam.Roles.editor. |
default_role |
The role used at sign-in when the account elects none. |
organizational_unit |
A folder-like path, for example /engineering/. Row scopes can match on it. |
service_account |
true marks a machine identity that signs in with API keys, not with a password. |
mfa_enabled |
true after the account finished MFA (multi-factor authentication) setup. |
must_change_pw |
true forces a password change at the next sign-in. |
federated_identities |
The single sign-on links, one per provider. See Single sign-on with OIDC. |
The status lifecycle
Section titled “The status lifecycle”A human account you create stores pending, even when you submit active.
The account completes its bootstrap with its first credential, and that first
sign-in flips it to active. Two exemptions exist: a service account is
created active, and an account provisioned by single sign-on keeps
active. An explicit suspended or disabled status is kept as submitted.
A pending account may sign in with its first credential. A suspended or
disabled account may not sign in at all; sign-in answers 403 Account is suspended (or disabled).
1. Create the account
Section titled “1. Create the account”- Open Configure → Access → Accounts and select New.
- Fill in
email,name, and at least one role inroles. - Select Save.
Facet opens the standard document form route and stores the account.
2. Send the first credential
Section titled “2. Send the first credential”Open the account page and find the credential actions below the document
view. Two operator routes exist. Both require the provision_credentials
permission; the backend re-checks it on every call.
Option A — temporary password
(POST /Api/iam/accounts/:id/temporary-password):
-
Select Generate password. Facet returns a 16-character password in four dashed groups, for example
K7M4-9XQ2-WBTD-H3PN. -
Facet shows the password exactly once. Copy it and hand it to the person over a safe channel. Nothing stores or emails the plaintext.
-
The route sets
must_change_pw, so the first sign-in asks for a new password before any session starts. -
The route refuses a service account and a
suspendedordisabledaccount with422. Apendingaccount is accepted. -
The route also clears any pending invite link. The password replaces the link, so the older email stops working at once.
Option B — invite link (
POST /Api/iam/accounts/:id/invite): -
Select Send invite. Facet mints a single-use link and emails it to the account address.
-
The link stays valid for the credential-link window. The default is 24 hours (
iam.change_password_expiration). -
The person opens the link and sets a password. Facet signs them in.
-
A second invite replaces the first link. The older email stops working at once.
-
The route refuses a service account with
422. It accepts every other status,suspendedanddisabledincluded, so an operator can hand back access through the invite. -
The two routes differ on purpose. A temporary password is refused for a
suspendedordisabledaccount, because the person cannot sign in to use it. An invite is allowed, because the person can accept the link and set a password first. The account still needsactivebefore the sign-in itself works.
3. Read the credential states
Section titled “3. Read the credential states”The credential panel on the account page reads
GET /Api/iam/accounts/credential-states?id=… when it loads. The route takes
one or more id query parameters and answers one entry per account, in a
states array. It is a batch read for the account tables: list the ids you
need, and get one state for each. The route needs provision_credentials on
iam.Account.
Each entry states:
| Field | Meaning |
|---|---|
has_password |
A password exists. |
must_change_pw |
The next sign-in forces a password change. |
mfa_enabled |
MFA is on. |
invite_pending |
An invite link is live. |
federated |
The account holds a single sign-on link. |
The action labels follow this state: Send invite or Resend invite, Generate password or Regenerate password.
4. Suspend or disable an account
Section titled “4. Suspend or disable an account”Edit the account document and set status to suspended or disabled. The
next sign-in attempt answers 403. Existing sessions keep working until their
access token expires; see
Sessions, refresh tokens and lockouts.
A service account has no sign-in at all. It cannot log in with a password, and password-reset requests for it are silent no-ops. Its purpose is to hold API keys — see Machine access: API keys.
5. Delete an account
Section titled “5. Delete an account”Deleting an account is a normal document delete. Select the account, and confirm the delete. The row becomes a tombstone; the history stays.
The role-authority guard adds one rule: you cannot delete an account whose
highest role level is above your own level. The delete answers 403 in that
case. See Roles and permission lines for
the guard.
6. Restore a deleted account
Section titled “6. Restore a deleted account”Open Configure → Access → Accounts, switch to the deleted list, and select Restore. The API route is:
curl -k -X POST -H "Authorization: Bearer $FACET_API_KEY" \ -H "Content-Type: application/json" -d '{}' \ "https://facet.localhost:3443/Api/iam/Account/01J8Z0A7G3Q5M2X9K4T6VBNR8D/restore"Replace 01J8Z0A7G3Q5M2X9K4T6VBNR8D with the account id. The call needs no
body. The answers:
| Answer | Meaning |
|---|---|
200 |
The account is live again, with its pre-delete content. |
409 |
The account is not deleted. |
404 |
No mutation history exists for this id. |
403 |
Your role lacks update on iam.Account. |
422 |
Degenerate history: a delete with no change before it. |
A restore also brings back the child records the delete removed, when the delete cascaded. See Rolling back changes for the mechanism.
The first administrator
Section titled “The first administrator”A fresh deployment has no account to sign in with. Create the first one on the server:
facet seed:admin ops@your-company.tldThe command prints a one-time password once. Sign in with it, and Facet asks for a new password. The command refuses to run when an account with that email already exists; recover a lost password through the reset flow instead.
Troubleshooting
Section titled “Troubleshooting”The credential buttons do not show
Section titled “The credential buttons do not show”Your role lacks provision_credentials on iam.Account. Ask an
administrator, or add the line
{"action": "provision_credentials", "on": "iam.Account"} to your role.
The invite email never arrives
Section titled “The invite email never arrives”- Check the spam folder.
- Check the mail settings of the instance.
- Send the invite again; the new link replaces the old one.
A password sign-in answers 403 Account is suspended
Section titled “A password sign-in answers 403 Account is suspended”An administrator set the status. Ask them to return it to active.
The restore answers 409
Section titled “The restore answers 409”The account is not deleted. A restore only works on a tombstone.
Related
Section titled “Related”- Roles and permission lines — the named actions this page uses.
- Assigning roles and role election — the
rolesarray anddefault_role. - Enforcing MFA — the
mfa_enabledflag and the MFA reset action. - Machine access: API keys — how service accounts authenticate.
- Single sign-on with OIDC — the
federated_identitiesfield and JIT provisioning. - Sign in, MFA, reset your password — the account holder’s side of the flows.
- Internals on GitHub: iam.md, access-accounts.md.