Signing in

The field app signs a member in once per device and keeps the token in secure storage (Keychain on iOS, Keystore on Android). Each sign-in needs a device_name, such as Pixel 9 (Kerry-Ann). Signing in again with the same name replaces that device’s old token, so reinstalling the app doesn’t leave stale tokens behind.

Email and password

POST /v1/auth/token

{ "email": "rep@example.com", "password": "…", "device_name": "Pixel 9" }

A correct password returns 201 with the token. A wrong one returns 422 with an error on email.

Two-factor sign-in

If the member has two-factor sign-in turned on, the first attempt returns 422 with an error on code:

{
  "message": "Enter the code from your authenticator app.",
  "errors": { "code": ["Enter the code from your authenticator app."] }
}

Show a code field and send the same request again with code, or with recovery_code if they’ve lost their device. Each recovery code works once.

Texted code

Reps added by phone number usually have no password. They sign in with a six-digit code instead:

1. POST /v1/auth/phone/code with identifier set to their phone number or staff ID. The response is always 202, so it never reveals whether a number is registered.
2. POST /v1/auth/phone/token with the same identifier, the code and a device_name.

Codes last 10 minutes and lock after 5 wrong guesses. Members with two-factor sign-in can’t use texted codes, because a text message would bypass their second factor.

After signing in

Call GET /v1/me to get the member’s organisations. If there’s more than one, let the rep choose and remember the choice. Then run a full sync.

Signing out

DELETE /v1/auth/token revokes the token the request was made with. The member’s other devices stay signed in. Clear the offline data and any queued store checks only after the queue has been sent, or warn the rep first.

Any 401 means the token is gone, for example because a manager removed the rep. Send the rep back to the sign-in screen.