How to sign up using basic auth

You will need the username and password of an active user in your Betterez backend.

We recommend creating an specific user for the API unless you want to track usage by specific users.

Basic Access Authentication token

This endpoint uses Basic Access Authentication to authenticate a User, using username and password.

For example: a User with username user@btrz.com and password secret1 should send a header Authorization with the result of Base64 encoding both strings

echo -n "user@btrz.com:secret1" | base64
//dXNlckBidHJ6LmNvbTpzZWNyZXQx

The basicAuthToken in this example would be `dXNlckBidHJ6LmNvbTpzZWNyZXQx`

Login

To login and get the JWT for use in other requests you will perform a POST into the https://api.betterez.com/accounts/users

The audience parameter must be completed with the name of the Application that is authenticating the User.

A full request with curl will look like this.

Notice that the data (after --data in curl) is a stringified json object.

Multi-factor authentication (MFA)

When the user or the account has multi-factor authentication (MFA) enabled, the login flow changes as follows.

User already has MFA enabled

  1. Send POST /accounts/users with Basic Auth and body {"audience": "betterez-app"} (no totpToken).
  2. The API responds with 401 and body {"code": "MFA_REQUIRED", "message": "Two-factor authentication code is required."}.
  3. Prompt the user for the 6-digit code from their authenticator app (TOTP).
  4. Resend the same request with the code in the body: {"audience": "betterez-app", "totpToken": "123456"} (replace with the actual code).
  5. If the code is valid, the API returns 200 with user, token, shortToken, etc. If the code is wrong or expired, the API returns 401 with {"code": "MFA_VERIFICATION_FAILED", ...}; ask the user for a new code and retry from step 4.

Request body (Audience) with MFA: In addition to audience, you may send totpToken (string, 6-digit TOTP code). It is required when the user has mfaEnabled: true; otherwise the server responds with MFA_REQUIRED.

User must set up MFA (first time)

MFA can be required at the account level (“MFA required for all users”) or per user (enforceMFA). If the user does not have MFA enabled yet but MFA is required:

  1. Send POST /accounts/users with Basic Auth and body {"audience": "betterez-app"}.
  2. The API responds with 200 and includes enableMFAforUser: true in the response. The response still includes a token, but the client must not establish a full login session.
  3. Redirect the user to your MFA setup flow. Use the Accounts API to start MFA enrollment (e.g. POST /accounts/users/{userId}/mfa to get the QR/otpauth URL), have the user scan the QR code with an authenticator app, then verify the code and enable MFA. After MFA is enabled, the user can log in again; the next login will follow the “User already has MFA enabled” flow if you omit totpToken, or succeed with totpToken in the body.

Summary of response codes

Scenario Response Action
Login OK, no MFA / MFA already satisfied 200, token + user Use token; session established.
Login OK, but MFA setup required 200, token + user + enableMFAforUser: true Do not establish full session; redirect to MFA setup.
User has MFA, no totpToken sent 401, MFA_REQUIRED Prompt for 6-digit code; resend with totpToken.
User has MFA, totpToken invalid or expired 401, MFA_VERIFICATION_FAILED Prompt for a new code; resend with totpToken.

For the full API contract (request/response schemas, all error codes), see the Accounts API documentation for POST /users.