Bearer Tokens

This page documents the concrete request/response flow for obtaining, using, resetting, and revoking a Lexabit API bearer token.

Obtaining a token

POST /auth/v1/login

Request body:

Field	Required	Notes
email	Yes
password	Yes
entity_type	No	String, max 50 characters
device_name	No	String, max 255 characters
recaptcha_token	No	String
context	No	portal or admin

recaptcha_token is optional in the schema, but depending on context (for example, repeated failed attempts or other risk signals) production may require a valid reCAPTCHA token to complete login. An email+password-only request that omits it can still be rejected in those cases.

The API spec does not document the exact purpose of entity_type and device_name — they're accepted by the endpoint, but the usual purpose described here is a general note, not a guaranteed behavior. In practice, entity_type is typically used to disambiguate a login when an email is shared across entity types, and device_name to label the issued token for use when managing multiple sessions.

curl -X POST https://api.lexabit.com/auth/v1/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

A successful response includes a bearer token in the standard data/meta envelope. A 422 response indicates a validation error (for example, missing or malformed fields).

Using the token

Send it on every subsequent request:

curl https://api.lexabit.com/auth/v1/me \
  -H "Authorization: Bearer <token>"

GET /auth/v1/me returns the currently authenticated user and is a good way to confirm a token is valid.

Refreshing a token

POST /auth/v1/refresh

Issues a new token and revokes the one used to authenticate the request. Requires a valid bearer token.

Revoking a token (logout)

POST /auth/v1/logout

Revokes the token used to authenticate the current request. To revoke every token issued to the account (for example, after a suspected credential compromise), use:

POST /auth/v1/logout-all

Both require a valid bearer token.

Resetting a forgotten password

If a user has forgotten their password, the reset flow is three steps:

1. Request a reset link:

   POST /auth/v1/forgot-password

   Body: email (required).

2. Validate the reset token (used by the reset form to confirm the link is still valid and pre-fill the email address):

   GET /auth/v1/reset-password/{uuid}

3. Submit the new password:

   POST /auth/v1/reset-password

   Body: token (the UUID from the reset link), password, and password_confirmation.

None of the password-reset endpoints require a bearer token — they authenticate via the emailed reset token instead.