> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancestraldev.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Avalex Registration Keys API — Master Admin Onboarding

> Generate and list single-use cryptographic registration keys that allow new staff members to create Avalex accounts. Restricted to the Master Admin.

Registration keys are how new staff accounts enter Avalex. Instead of allowing open self-registration, Avalex requires each new staff member to present a unique, single-use key when calling `POST /staff/register`. This keeps account creation under strict administrative control — only the Master Admin can generate keys, and each key is consumed the moment it is used. If a key is compromised before use, it can simply be discarded and a fresh one generated.

<Note>
  Both endpoints under `/admin/registration-keys` are restricted to the **Master Admin** account. No other role or permission level grants access to these routes.
</Note>

***

## Generate a Registration Key

Creates a new single-use registration key and returns it in plaintext. Share this key out-of-band (for example, via a secure message) with the person who will be registering.

```bash theme={null}
curl -X POST http://localhost:8080/admin/registration-keys \
  -H "Authorization: Bearer <master-admin-token>"
```

**Response — 201 Created**

```json theme={null}
{
  "key": "a1b2c3d4e5f67890abcdef1234567890"
}
```

<Warning>
  The key value is shown **only once**, at the moment of creation. It is not stored in a retrievable form and will not appear in any subsequent API response. Copy it immediately and deliver it securely to the intended staff member. If the key is lost before use, generate a new one.
</Warning>

***

## List Registration Keys

Returns metadata for all registration keys ever generated in your Avalex account. This gives you an audit trail of key creation without exposing the key values themselves.

```bash theme={null}
curl http://localhost:8080/admin/registration-keys \
  -H "Authorization: Bearer <master-admin-token>"
```

**Response — 200 OK**

```json theme={null}
[
  {
    "id": "c6a2b8e3-d4f5-4a1b-9c7e-0f1a2b3c4d5e",
    "used": false,
    "createdBy": "master",
    "createdAtEpochMillis": 1723140000000
  }
]
```

<Note>
  The actual key string is **never returned** by this endpoint — only the key's metadata. If you need to send a key to a staff member, you must generate a new one via `POST /admin/registration-keys`.
</Note>

### Response Fields

<Expandable title="Registration key metadata fields">
  <ResponseField name="id" type="string">
    Unique identifier for this key record. Use this ID to track which keys have been used.
  </ResponseField>

  <ResponseField name="used" type="boolean">
    Whether this key has already been consumed by a staff registration. Once `true`, the key cannot be used again.
  </ResponseField>

  <ResponseField name="createdBy" type="string">
    Username of the admin who generated this key. Will be `"master"` for keys created by the Master Admin.
  </ResponseField>

  <ResponseField name="createdAtEpochMillis" type="number">
    Unix timestamp in milliseconds representing when this key was generated.
  </ResponseField>
</Expandable>

***

## Using a Registration Key

Once you have generated a key and delivered it to a new team member, they submit it as part of the `POST /staff/register` request body alongside their chosen username, email, password, and desired roles. The key is validated and marked as used atomically with account creation.

```bash theme={null}
curl -X POST http://localhost:8080/staff/register \
  -H "Content-Type: application/json" \
  -d '{
    "registrationKey": "a1b2c3d4e5f67890abcdef1234567890",
    "username": "newstaff",
    "email": "staff@example.com",
    "password": "securepassword123",
    "roleIds": ["role_support"]
  }'
```

For the full registration endpoint reference — including all request fields, success response, and error codes — see the [Staff Management](/api/staff/overview#register-a-new-staff-member) page.

<Tip>
  Generate a fresh key for each new staff member rather than reusing or pre-generating batches. Single-use keys ensure that even if a key is intercepted in transit, it cannot be used a second time, and you can trace exactly which registration consumed which key.
</Tip>