Redeem an Enrollment

An administrator has created a GoodMem account for you and sent you an enrollment credential — a one-time secret that starts with gme_. This guide turns that credential into your own API key: a key that belongs to you, authenticates as you, carries whatever authority your account has, and does not expire. The administrator's side of this exchange is covered in Onboard a User.

The enrollment credential is good for exactly one key, and it expires 24 hours after it was created. If yours has expired, ask your administrator for a new one.

Before You Start

• The goodmem CLI installed, and your server's URL (for example https://goodmem.example.com:9090).
• The enrollment credential from your administrator.
• No API key. Enrollment is designed to work without one.

1. Supply the Credential

goodmem user enroll accepts the credential from exactly one of four sources:

Run interactively with no source at all and the CLI falls back to the hidden prompt, which is the sensible default for a human at a terminal. Supplying more than one source is an error. Passing the credential with --token works, and the CLI will remind you that it just landed in your shell history and in the process listing of anyone who ran ps at the right moment.

2. Run the Enrollment

goodmem user enroll --token-prompt

By default the CLI generates the key material itself, locally, before it talks to the server. It saves the exact key it generated in an owner-only recovery file under ~/.goodmem/enrollment-recovery/, submits it along with your credential, prints the key after the server confirms, and then deletes the recovery file.

The reason for this choreography: this is your first credential. If the exchange fails partway — a dropped connection, a timeout — you have no other key with which to ask the server what happened. Because the CLI retained the exact key it proposed, rerunning the same command is safe: the server either completes the enrollment or recognizes the retry and confirms the key it already stored. Either way you end up with a working key instead of a burned credential.

A successful run looks like this:

Enrollment Completed: true
API Key ID:          0198c0f2-4d31-7a8e-9b1c-3f6d82a90e44
Key Prefix:          gm_mzxw
Raw API Key:         gm_mzxw6ytboiww6z3foj2xezltoq

The raw API key is shown once. Store it in your secret manager or password vault before doing anything else.

If the Command Fails

• On any transport or server error, the CLI keeps the recovery file and tells you where it is. Run the same command again.
• An expired, revoked, already-consumed, or simply wrong credential gets one generic rejection; the server does not distinguish the cases. Confirm the credential with your administrator, who can inspect its status and issue a replacement.
• The completion endpoint is rate-limited per source address. If you are rejected for rate limiting, wait a minute and retry — the recovery file makes the retry safe.

Letting the Server Generate the Key

goodmem user enroll --token-prompt --server-generate-key

This skips the local key generation and recovery file; the server mints the key and returns it once. It is the simpler contract, and some environments prefer key material that never touched a client's random-number generator.

3. Configure the CLI

Point a CLI profile at your server with the new key:

goodmem profile create default --url https://goodmem.example.com:9090 --api-key gm_...

SDKs and direct REST calls use the same key in the x-api-key header.

If Your Key Cannot Do Anything

Enrollment produces a credential, and only a credential. Your authority comes from the roles and grants on your account, which your administrator assigns separately. If the administrator skipped that step, your new key authenticates successfully and is then denied almost everything — the key works; there is nothing it is allowed to do. The fix is on the administrator's side: assigning the standard USER role, described in Onboard a User. How keys relate to the authority behind them is covered in API Keys and Ceilings.

Enrolling over REST

The CLI wraps a single REST call, which you can make directly. It is the only authorization-related endpoint that takes no x-api-key header — the enrollment credential is the authentication.

curl -X POST https://goodmem.example.com:8080/v1/user-enrollments:complete \
  -H "Content-Type: application/json" \
  -d '{"enrollmentToken": "gme_..."}'

This is server-generated mode: the response carries the raw key exactly once, with the lost-response caveat above. For the retry-safe equivalent of the CLI's default, generate a UUID and a canonical gm_ key yourself and send all three fields — enrollmentToken, apiKeyId, and rawApiKey. The two key fields travel as a pair; sending one without the other is invalid. Retrying the identical request after a lost response returns the stored result with alreadyCompleted: true.

Responses are marked Cache-Control: no-store, and rate-limited requests return HTTP 429 with a Retry-After header.