In this section · 3 articles

Sign people in from a mobile app

Sign people in to your mobile app with their Laramin password and, when they use two-factor authentication, their code. Keep them signed in with refresh tokens, sign them out, reset a forgotten password, and handle every refusal, as Core 12.8 does it.

Applies to
Core 12.8 and later
Who can do this
Developer
On this page

Your app sends the person's sign-in name and password to your Laramin and gets back two tokens: a short-lived access token for every request, and a long-lived refresh token to get a new pair without asking for the password again. If the person uses two-factor authentication, the app asks for their code before it gets the tokens. The app never holds an OAuth client secret: your Laramin adds it on the server.

Before you start

  • Whoever runs the server sets PASSPORT_PASSWORD_CLIENT_ID and PASSPORT_PASSWORD_CLIENT_SECRET, the OAuth client your Laramin uses for app sign-ins. Without them every sign-in answers 500 TOKEN_ISSUANCE_FAILED with "Mobile authentication is not configured."
  • Signing in, the two-factor step and the token refresh need no key. Other requests made while nobody is signed in, such as Core Mobile's start-up settings, need an API consumer key or the platform API key.
  • Each person who signs in needs Enable API Access on their account, an active account and a verified email address. Accounts created from the app get API access automatically. See Edit a user.

Sign in

POST /api/v1/mobile/login needs no key.

Bash
curl https://crm.example.com/api/v1/mobile/login \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "correct-horse-battery"}'

Replace the highlighted values with your own.

email takes whatever the person signs in with: an email address, username or phone number. Leave out scope: the default, mobile, lets the app read and change data as the person. scope accepts only mobile, read and write, separated by spaces. Anything else answers 400 BAD_REQUEST before the account is looked at.

JSON
{
  "success": true,
  "message": "Login successful.",
  "data": {
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOi…",
    "refresh_token": "def50200a1b2c3…"
  },
  "meta": { "request_id": "6f1d0c2e-…", "locale": "en" }
}

If the answer has data.two_factor instead of the tokens, the person uses two-factor authentication: go on to the two-factor step, under Two-factor authentication below. Otherwise:

  1. Keep both tokens in the phone's secure storage, such as the iOS Keychain or Android Keystore. Never in plain preferences or logs.
  2. Send the access token on every request as Authorization: Bearer <access_token>.
  3. Note when it expires: expires_in seconds from now.
  4. Load the person's details with GET /api/v1/mobile/profile.

By default an access token lasts 60 minutes and a refresh token 30 days. Whoever runs the server can change these with PASSPORT_TOKEN_TTL (minutes) and PASSPORT_REFRESH_TTL (days).

When sign-in is refused

Branch on error.code, never on the message. Only someone who typed the right password learns the state of the account: a wrong password always gets the 401, whatever the account's state. The one exception is a network address your Laramin's IP rules refuse: from Core 12.8.5 it gets the 403 below before the password is checked, as on the web.

AnswerCodeWhat to show
401UNAUTHENTICATED"Invalid credentials or inactive account." The name or password is wrong. Unknown accounts get the same answer.
400BAD_REQUESTThe app asked for a scope other than mobile, read or write. Fix the app.
403UNAUTHORIZEDAPI access is off for this account. An administrator must turn on Enable API Access.
403UNAUTHORIZED, message "Access denied from your network address. Please contact your administrator."From Core 12.8.5: your Laramin's IP rules refuse the phone's network address for this account (or, for an unknown account, the global rules do). No token or two-factor challenge is issued and no failed attempt is counted. Show the message: the person signs in from an allowed network, or asks an administrator.
403ACCOUNT_SUSPENDEDThe account has been deactivated.
403EMAIL_UNVERIFIEDThe person must verify their email address first. A new code has been emailed, and errors.registration_session lets the app go straight to the code screen. See Finish a sign-up that was interrupted.
403PASSWORD_CHANGE_REQUIREDAn administrator set a temporary password or asked the person to change theirs. Send them to Forgot password (below) to choose a new one.
403TWO_FACTOR_ENROLMENT_REQUIREDYour Laramin requires two-factor authentication and the person hasn't set it up. Open errors.enrol_url in the browser, where they set it up in Profile › Security, then sign in again.
423ACCOUNT_LOCKEDToo many wrong passwords or codes. errors.retry_after_seconds says how long to wait: show a countdown, not "wrong password".
429RATE_LIMITEDToo many attempts from this network. Wait for Retry-After.
500TOKEN_ISSUANCE_FAILED"Sign-in is temporarily unavailable." A problem on the server, not a wrong password. Ask the person to try again shortly. It doesn't count toward the lockout.

Lockouts follow Enable brute-force protection, Max login attempts and Lockout duration (minutes) in Security settings. The right password doesn't lift a lockout early.

Two-factor authentication

For an account that has set up two-factor authentication, the right password answers 200 with a challenge and no tokens:

JSON
{
  "success": true,
  "message": "Enter the code from your authenticator app to finish signing in.",
  "data": {
    "two_factor": {
      "challenge_token": "Zm9vYmFy…",
      "expires_at": "2026-11-08T10:05:00+05:30",
      "expires_in": 300,
      "methods": ["totp", "recovery_code"],
      "max_attempts": 5
    }
  },
  "meta": { "request_id": "6f1d0c2e-…", "locale": "en" }
}
  1. Show a code screen. Offer the authenticator code, and a way to use a recovery code instead.

  2. Send the challenge with exactly one of code (the 6 digits from the authenticator app) or recovery_code:

    Bash
    curl https://crm.example.com/api/v1/mobile/login/two-factor \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -d '{"challenge_token": "Zm9vYmFy…", "code": "482913"}'
  3. The right code answers with the access and refresh tokens, exactly like a sign-in without two-factor.

The challenge lasts 5 minutes and allows 5 wrong codes. It works once, and a new sign-in replaces it. Each recovery code works once. The endpoint needs no key and allows 10 requests a minute from one address. Never retry it automatically: a repeated request spends an attempt.

AnswerCodeWhat to do
422TWO_FACTOR_CODE_INVALIDWrong code. Clear the field and let them try again.
422TWO_FACTOR_CHALLENGE_EXPIREDThe challenge expired, was used, ran out of tries or was replaced by a newer sign-in, or the person's two-factor was reset. Go back to the sign-in screen.
423ACCOUNT_LOCKEDWrong codes count toward the lockout together with wrong passwords. Show the countdown from errors.retry_after_seconds.
403UNAUTHORIZED, ACCOUNT_SUSPENDED, EMAIL_UNVERIFIED, PASSWORD_CHANGE_REQUIREDThe same refusals as at sign-in, given only after the right code.
403UNAUTHORIZED, message "Access denied from your network address. Please contact your administrator."From Core 12.8.6: your Laramin's IP rules refuse the phone's network address for this account, for example because the phone changed network after the password, or a rule was added since. Checked before the code, so no attempt is used and nothing counts toward the lockout. The challenge still works from an allowed network until it expires.

When Require two-factor authentication is on in Security settings, it applies to the app too. A staff member who hasn't set up two-factor authentication gets 403 TWO_FACTOR_ENROLMENT_REQUIRED at sign-in, and a phone that's already signed in gets the same answer on its next request. Super admins and portal users aren't affected, as on the web.

Social sign-in and verifying a sign-up can answer with the same challenge or refusals, so handle them wherever the app receives tokens.

Keep the person signed in

Before the access token expires, or when a request answers 401, trade the refresh token for a new pair. The refresh needs no key:

Bash
curl https://crm.example.com/api/v1/mobile/refresh \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "def50200a1b2c3…"}'

The answer has the same shape as the sign-in. Replace both stored tokens: each refresh token works once, and the old pair stops working.

  • 401: the refresh token has expired or been revoked, or the account can no longer use the API. Clear both tokens and show the sign-in screen.
  • 403 UNAUTHORIZED, message "Access denied from your network address. Please contact your administrator.": from Core 12.8.5, your Laramin's IP rules refuse the phone's current network address for the account. Nothing is issued and the refresh token isn't used up: it works again from an allowed network. Show the message rather than signing the person out.
  • 500 TOKEN_ISSUANCE_FAILED: a problem on the server. Keep the tokens and try again later. Don't sign the person out.

Each person may refresh 10 times a minute, separately from sign-ins, so phones on one office network don't share a limit. Refresh only when needed, never in a loop. See API rate limits.

Example: refresh on 401 (JavaScript)

JavaScript
const BASE = 'https://crm.example.com/api/v1/mobile';

async function api(path, options = {}, retried = false) {
  const { accessToken } = await tokenStore.get();
  const res = await fetch(BASE + path, {
    ...options,
    headers: { Accept: 'application/json', Authorization: `Bearer ${accessToken}`, ...options.headers },
  });
  if (res.status === 401 && !retried && (await refresh())) {
    return api(path, options, true);
  }
  return res;
}

let refreshing = null; // one refresh at a time, however many requests failed
function refresh() {
  refreshing ??= (async () => {
    const { refreshToken } = await tokenStore.get();
    const res = await fetch(`${BASE}/refresh`, {
      method: 'POST',
      headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
      body: JSON.stringify({ refresh_token: refreshToken }),
    });
    if (res.status === 401) {
      await tokenStore.clear(); // back to the sign-in screen
      return false;
    }
    if (!res.ok) {
      return false; // the server is having trouble: keep the tokens, try again later
    }
    const { data } = await res.json();
    await tokenStore.set({ accessToken: data.access_token, refreshToken: data.refresh_token });
    return true;
  })().finally(() => { refreshing = null; });
  return refreshing;
}

When a signed-in request is refused

AnswerCodeWhat to do
403PASSWORD_CHANGE_REQUIREDAn administrator asked the person to change their password. Send them to Forgot password. Choosing a new password signs them out, so they sign in again with it.
403TWO_FACTOR_ENROLMENT_REQUIREDYour Laramin now requires two-factor authentication. Open errors.enrol_url in the browser so they can set it up.
403UNAUTHORIZED, ACCOUNT_SUSPENDEDAPI access was turned off, or the account deactivated.
403UNAUTHORIZED, message "Access denied from your network address. Please contact your administrator."Your Laramin's IP rules refuse the phone's current network address. Show the message and keep the tokens: requests work again from an allowed network. Before Core 12.8.6 this answer had no error.code: its body was {"status": false, "message": "Access denied from your network address."}.

Signing out still works while a password change or two-factor setup is required.

Sign out

Bash
curl -X POST https://crm.example.com/api/v1/mobile/logout \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

This revokes the access token and its refresh token, so neither can be used again. The person's other devices stay signed in. Delete both tokens from the phone as well.

Your Laramin also ends app sign-ins when:

  • An administrator deactivates the account or turns off Enable API Access: the app's next request answers 403.
  • An administrator sets the person's password, the person resets a forgotten password (on the web or in the app), or they change it in Profile › Password on the web. This signs them out of the app on every device and revokes their API tokens: the next request answers 401.
  • The person changes their password in the app with POST /api/v1/mobile/password. Every other device is signed out; the phone that made the change stays signed in.

Log Out Other Devices in Sessions & devices ends browser sessions only. It doesn't sign anyone out of the app.

Reset a forgotten password

  1. Ask for a code. The answer is the same whether or not the address has an account:

    HTTP
    POST /api/v1/mobile/password/forgot
    Content-Type: application/json
    
    { "email": "user@example.com" }
  2. The person receives a 6-digit code by email. It lasts 15 minutes and allows 5 wrong tries.

  3. Send the code with the new password:

    HTTP
    POST /api/v1/mobile/password/reset
    Content-Type: application/json
    
    { "email": "user@example.com", "code": "482913", "password": "a-new-long-password" }
  4. On success, take the person to the sign-in screen. No tokens are issued. A wrong, expired or used-up code answers 422 with one message for every case.

Both endpoints need no key and allow 3 requests a minute. The new password must meet your Laramin's password rules. A reset also clears a password change an administrator asked for, and signs the person out of the app everywhere.

Other ways to sign in