GoodMemGoodMem
ReferenceAPIREST APIUsers

Complete human-user enrollment

POST /v1/user-enrollments:complete: Exchanges a one-time enrollment credential for the human's initial self-owned API key.

POST
/v1/user-enrollments:complete

Exchanges a one-time enrollment credential for the human's initial self-owned API key. This endpoint does not use ordinary API-key authentication. Omit both optional key fields for server generation; a fresh response discloses the raw key exactly once and cannot be safely retried after an ambiguous outcome. Supply and retain both fields for client mode, where only an exact tuple retry is safe and raw material is never echoed. Status precedence is request-shape errors (400), then the same generic authentication failure for every nonblank unusable enrollment (401); key conflicts or concurrent lifecycle winners return 409, rate limits return 429, and unexpected failures return 500.

Header Parameters

GoodMem-Timeout-Ms?integer

Optional waiting budget in milliseconds, measured from REST servlet ingress and shared across all internal gRPC calls. Supply one decimal integer from 1 to 86400000. Omission adds no deadline. Existing shorter deadlines still apply. Expiry returns HTTP 504 before streaming starts; after streaming starts, no successful completion event is sent. Use SSE or opt into GoodMem-Stream-Terminal for an explicit terminal outcome. Retrieval work is cooperatively cancelled. An accepted mutation may still commit after timeout or disconnect; a failed response does not imply rollback.

Formatint64
Range1 <= value <= 86400000

Request Body

application/json
  1. body

Exchanges one enrollment credential for the target human's initial API key. Omit both apiKeyId and rawApiKey for server-generated key material, or supply both for exact-retry-safe client-generated completion; supplying only one is invalid.

enrollmentToken*string

Required one-time enrollment credential. Never log or persist it.

Match^gme_[a-z2-7]{52}$
Length56 <= length <= 56
Example"gme_mzxw6ytboiww6z3foj2xezltoqxxezltoqxxezltoqxxezltoqxa"
apiKeyId?|

Optional client-generated API-key UUID retained for exact retries. Must be supplied together with rawApiKey, or both fields must be omitted.

Formatuuid
Example"550e8400-e29b-41d4-a716-446655440000"
rawApiKey?|

Optional canonical client-generated API key. Must be supplied together with apiKeyId, never logged, and retained for exact retries; omit both fields for server generation.

Match^gm_[a-z2-7]{26}$
Length29 <= length <= 29
Example"gm_mzxw6ytboiww6z3foj2xezltoq"

Response Body

Initial API key published, with one-time raw key material only for a fresh server-generated completion; or an exact client-mode retry replayed without raw material

application/json
  1. response

Initial API-key metadata, exact-retry classification, and one-time raw key material only for a fresh server-generated completion. Client-supplied keys are never echoed.

apiKey*

OUTPUT_ONLY; metadata for the newly published initial API key.

alreadyCompleted*boolean

OUTPUT_ONLY; true when the exact completion tuple already committed.

rawApiKey?|

OUTPUT_ONLY; one-time raw API key returned only by a fresh server-generated completion. Omitted for client-supplied completion and every replay.

Match^gm_[a-z2-7]{26}$
Length29 <= length <= 29
Example"gm_mzxw6ytboiww6z3foj2xezltoq"
Example Request
curl -X POST 'https://your-goodmem-server.example.com/v1/user-enrollments:complete' \  -H 'GoodMem-Timeout-Ms: 30000' \  -H 'Content-Type: application/json' \  -d '{  "enrollmentToken": "gme_mzxw6ytboiww6z3foj2xezltoqxxezltoqxxezltoqxxezltoqxa",  "apiKeyId": "550e8400-e29b-41d4-a716-446655440000",  "rawApiKey": "gm_mzxw6ytboiww6z3foj2xezltoq"}'
Example Response
{  "apiKey": {    "apiKeyId": "550e8400-e29b-41d4-a716-446655440000",    "subjectPrincipalId": "70e025f6-76ca-4cbe-b8fc-7dab8e84590a",    "ownerPrincipalId": "b3303d0a-1a4a-493f-b9bf-38e37153b5a2",    "authorityMode": "INHERIT_SUBJECT",    "ceiling": [      {        "assignedResource": {          "resourceId": "550e8400-e29b-41d4-a716-446655440000"        }      }    ],    "ceilingOmitted": true,    "keyPrefix": "gm_12345...",    "status": "ACTIVE",    "lifecycleState": "NOT_YET_VALID",    "labels": {      "purpose": "production",      "service": "recommendation-engine"    },    "expiresAt": 1672531200000,    "validFrom": 1640908800000,    "revokedAt": 1640995200000,    "revokedById": "b3303d0a-1a4a-493f-b9bf-38e37153b5a2",    "lastUsedAt": 1640995200000,    "createdAt": 1640908800000,    "updatedAt": 1640908800000,    "createdById": "b3303d0a-1a4a-493f-b9bf-38e37153b5a2",    "updatedById": "b3303d0a-1a4a-493f-b9bf-38e37153b5a2"  },  "alreadyCompleted": true,  "rawApiKey": "gm_mzxw6ytboiww6z3foj2xezltoq"}