Onboard a User

This guide is for administrators adding a person to a GoodMem instance. The result of onboarding is an enrollment credential, which you deliver to the person. They exchange it for their own API key by following Redeem an Enrollment. Onboarding never issues the person's API key; only they can do that.

Creating a user has no side effects. A freshly created user has no credential, no role, and no grants — it is an identity and nothing more. Onboarding is the three administrative steps that turn that identity into a usable account:

1. Create the user.
2. Assign the instance USER role, which supplies the ordinary self-service capabilities.
3. Create a one-time enrollment credential bound to that user.

The goodmem user onboard command runs all three. Each step is a separate RPC and a separate audit record; the command coordinates them but does not pretend they are one transaction.

Before You Start

• goodmem CLI installed and authenticated.
• Authority to create users and manage enrollments. The instance ADMIN role covers both. If you authenticate with a scoped API key, its ceiling must cover CREATE_USER, MANAGE_ACCESS, and MANAGE_USER_ENROLLMENT.

Enrollment administration is restricted to authenticated humans. A service identity cannot create enrollment credentials, and the authority cannot be granted to all authenticated principals. This keeps workloads and broad grants away from account bootstrap.

The Short Path

goodmem user onboard \
  --email [email protected] \
  --username sarah \
  --display-name "Sarah"

Only --email is required. The command prints progress for each step to stderr, then the result:

User ID:             70e025f6-76ca-4cbe-b8fc-7dab8e84590a
Role Assignment ID:  0198b9f4-c42f-7ae3-8c56-44d827ea03bd
Enrollment ID:       3f1c9d22-8a41-4f0e-9c37-5be2a17d6c91
Enrollment Token:    <one-time enrollment credential>

Deliver the token to the person over a channel you trust — a password-manager share, or a direct message on an internal system. The token is single-use, bound to that user, and expires 24 hours after creation.

For scripting, --quiet prints only the token, and --format json returns the full result including per-step status.

Skipping steps

• --skip-role creates the user and enrollment without assigning USER. Use this when the person should get a different set of capabilities — for example, only a space role assigned by a space administrator. They will be able to authenticate after enrolling, but can do very little until someone grants them authority.
• --skip-enrollment creates the identity and role only. Use this when you are provisioning accounts ahead of time and will create enrollments later. With this flag, --quiet prints the user UUID instead of a token.

When a step fails

The command generates every UUID client-side before the first RPC, and reports each step as SUCCEEDED, FAILED, UNKNOWN, or NOT_RUN. Completed steps are durable: if role assignment fails, the user still exists, and rerunning onboard would try to create a second user. Resume with the individual commands instead, using the IDs from the step report:

goodmem access-policy role-assignment assign \
  --principal 70e025f6-76ca-4cbe-b8fc-7dab8e84590a \
  --role USER --resource-kind INSTANCE
goodmem user enrollment create 70e025f6-76ca-4cbe-b8fc-7dab8e84590a

A step reported UNKNOWN means the CLI lost the response and cannot say whether the server committed. Inspect before retrying — goodmem user get <user-id> and goodmem user enrollment list <user-id> show what exists on the server.

The Manual Path

The same three steps as separate commands, for when you want each one explicit:

# 1. Create the identity
goodmem user create --email [email protected] --username sarah --display-name "Sarah"

# 2. Assign the standard instance role
goodmem access-policy role-assignment assign \
  --principal <user-uuid> --role USER --resource-kind INSTANCE

# 3. Create the enrollment credential
goodmem user enrollment create <user-uuid>

user create accepts --id for a stable client-provided UUID, useful when mirroring an external directory. The Built-in Roles reference lists what USER grants; substitute a different role, direct grants, or a space role via Share a Space if the defaults do not fit.

Managing Enrollments

A user has at most one open enrollment. The lifecycle commands:

goodmem user enrollment list <user-id>                     # history: pending, consumed, revoked, expired
goodmem user enrollment get <user-id> <enrollment-id>      # metadata only, never the token
goodmem user enrollment revoke <user-id> <enrollment-id>   # permanent
goodmem user enrollment create <user-id> --rotate-existing # revoke and replace atomically

Enrollments expire on their own after 24 hours. Creating a new enrollment after expiration needs no flag; replacing one that is still open requires --rotate-existing, which revokes the old credential and issues the new one in a single transaction. Revoke without replacement when an invitation was sent to the wrong person or the account should stay dormant.

Once the person has enrolled, the enrollment is consumed and cannot be reused. A user who already completed enrollment, or who already holds an API key, is no longer eligible for new enrollments — credential recovery at that point is ordinary API-key rotation, performed by the person with a key they still hold. Human keys are self-issued, so an administrator can revoke a compromised key but cannot mint the replacement.

REST Equivalents

Each CLI step maps to one endpoint:

The enrollment creation response contains the token exactly once and is served with Cache-Control: no-store. See the REST API reference for request bodies.

Further Reading

• Redeem an Enrollment — the guide to hand to the person you just onboarded.
• Users and Service Identities — why identity, role, and credential are separate steps.
• Security Model — how GoodMem evaluates authority once the person is enrolled.