Skip to main content

Documentation Index

Fetch the complete documentation index at: https://alphabet-06152314.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Alphabet secures every API request with JWT bearer tokens. When you log in you receive a short-lived access token (valid for 15 minutes) and a longer-lived refresh token (valid for 7 days). Include the access token in every request, and exchange the refresh token for a new pair before it expires. If you prefer a browser-based client, you can opt in to cookie transport and Alphabet writes HttpOnly Secure cookies instead of returning the tokens in the response body.
The default admin account seeded at startup uses the email admin@alphabet.local and the password Admin12345!. Change these credentials before deploying to any non-local environment.

​
Including a token in requests

Pass the access token in the Authorization header on every authenticated endpoint: 
Authorization: Bearer <accessToken>

​
Registration, confirmation, and login

1

Register an account

Send your details to POST /api/v1/auth/register. On success the API returns 201 Created with the new user record. Email confirmation may be required before you can sign in.
curl -X POST https://your-api/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "Password123!",
    "firstName": "Jane",
    "lastName": "Doe"
  }'
Request body
{
  "email": "user@example.com",
  "password": "Password123!",
  "firstName": "Jane",
  "lastName": "Doe"
}
Response — 201 Created
{
  "userId": "3f45ef0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "email": "user@example.com",
  "firstName": "Jane",
  "lastName": "Doe"
}
2

Confirm your email address

After registration, Alphabet sends a confirmation email. Extract the userId and token from the link and call POST /api/v1/auth/confirm-email. The response is 200 OK with no body.
curl -X POST https://your-api/api/v1/auth/confirm-email \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "3f45ef0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
    "token": "confirm-token-from-email"
  }'
Request body
{
  "userId": "3f45ef0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "token": "confirm-token-from-email"
}
3

Log in

Call POST /api/v1/auth/login with your credentials. Set useCookies to true if you want Alphabet to write HttpOnly cookies instead of returning tokens in the response body.
curl -X POST https://your-api/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "Password123!",
    "useCookies": false
  }'
Request body
{
  "email": "user@example.com",
  "password": "Password123!",
  "useCookies": false
}
Response — 200 OK
{
  "accessToken": "eyJ...",
  "refreshToken": "abc123..."
}
If MFA is enabled on the account, the login response returns an mfaToken instead of an accessToken. See the MFA guide for the follow-up steps.

​
Password management

​
Forgot password

If a user cannot remember their password, call POST /api/v1/auth/forgot-password with their email address. Alphabet always returns 200 OK regardless of whether the email matches an account, so you cannot use the response to enumerate users. 
curl -X POST https://your-api/api/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com" }'

​
Reset password

Once the user receives the reset email, extract the userId and token from the link and call POST /api/v1/auth/reset-password with their new password. 
curl -X POST https://your-api/api/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "3f45ef0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
    "token": "reset-token-from-email",
    "newPassword": "NewPassword456!"
  }'
A 200 OK response means the password was changed successfully.

​
Change password

An authenticated user can change their own password by calling POST /api/v1/auth/change-password. This endpoint requires a valid Authorization header. 
curl -X POST https://your-api/api/v1/auth/change-password \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "currentPassword": "Password123!",
    "newPassword": "NewPassword456!"
  }'

​
Logout

Call POST /api/v1/auth/logout to revoke the refresh token and clear any auth cookies. This endpoint requires a valid Authorization header. 
curl -X POST https://your-api/api/v1/auth/logout \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "abc123..." }'
If you are using cookie transport, the refreshToken field is optional — Alphabet reads the token from the alphabet_refresh_token cookie automatically.

​
Get the current user

GET /api/v1/auth/me returns the identity of the user associated with the current access token. Requires a valid Authorization header. 
curl https://your-api/api/v1/auth/me \
  -H "Authorization: Bearer <accessToken>"
Response — 200 OK 
{
  "userId": "3f45ef0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "email": "user@example.com",
  "roles": ["User"]
}
When you set useCookies: true in your login or refresh-token request, Alphabet writes two HttpOnly Secure SameSite=Lax cookies to the response:
Cookie nameContents
alphabet_access_tokenShort-lived JWT
alphabet_refresh_tokenLong-lived refresh token
Subsequent requests from a browser automatically include these cookies, so you do not need to manage token storage in JavaScript. The Authorization header takes precedence when both are present.
Cookie transport is recommended for browser-based single-page apps because it prevents tokens from being accessible to JavaScript and reduces XSS risk.

​
Error responses

All errors from the Alphabet API follow the RFC 7807 Problem Details format. 
{
  "title": "Login failed",
  "detail": "The email or password is incorrect."
}
StatusMeaning
400 Bad RequestValidation error or operation failure — check detail for the reason
401 UnauthorizedMissing or expired access token
For token refresh and session management, see the tokens guide.