Avalex Registration Keys API — Master Admin Onboarding

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.

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

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.

curl -X POST http://localhost:8080/admin/registration-keys \
  -H "Authorization: Bearer <master-admin-token>"

Response — 201 Created

{
  "key": "a1b2c3d4e5f67890abcdef1234567890"
}

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.

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.

curl http://localhost:8080/admin/registration-keys \
  -H "Authorization: Bearer <master-admin-token>"

Response — 200 OK

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

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.

Response Fields

Show Registration key metadata fields

string

Unique identifier for this key record. Use this ID to track which keys have been used.

boolean

Whether this key has already been consumed by a staff registration. Once true, the key cannot be used again.

string

Username of the admin who generated this key. Will be "master" for keys created by the Master Admin.

number

Unix timestamp in milliseconds representing when this key was generated.

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.

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 page.

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.

Authentication

License Validation

Resources

Staff & Admin

Audit Logs

Avalex Registration Keys API — Master Admin Onboarding

Generate a Registration Key

List Registration Keys

Response Fields

Using a Registration Key

​Generate a Registration Key

​List Registration Keys

​Response Fields

​Using a Registration Key

Generate a Registration Key

List Registration Keys

Response Fields

Using a Registration Key