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_andPASSWORD_ CLIENT_ ID PASSPORT_, the OAuth client your Laramin uses for app sign-ins. Without them every sign-in answersPASSWORD_ CLIENT_ SECRET 500TOKEN_with "Mobile authentication is not configured."ISSUANCE_ FAILED - 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/ needs no key.
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
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.
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
{
"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:
- Keep both tokens in the phone's secure storage, such as the iOS Keychain or Android Keystore. Never in plain preferences or logs.
- Send the access token on every request as
Authorization: Bearer <access_token>. - Note when it expires:
expires_inseconds from now. - 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_ (minutes) and PASSPORT_ (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.
| Answer | Code | What to show |
|---|---|---|
401 | UNAUTHENTICATED | "Invalid credentials or inactive account." The name or password is wrong. Unknown accounts get the same answer. |
400 | BAD_REQUEST | The app asked for a scope other than mobile, read or write. Fix the app. |
403 | UNAUTHORIZED | API access is off for this account. An administrator must turn on Enable API Access. |
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 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. |
403 | ACCOUNT_ | The account has been deactivated. |
403 | EMAIL_UNVERIFIED | The person must verify their email address first. A new code has been emailed, and errors. lets the app go straight to the code screen. See Finish a sign-up that was interrupted. |
403 | PASSWORD_ | An administrator set a temporary password or asked the person to change theirs. Send them to Forgot password (below) to choose a new one. |
403 | TWO_ | Your 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. |
423 | ACCOUNT_LOCKED | Too many wrong passwords or codes. errors. says how long to wait: show a countdown, not "wrong password". |
429 | RATE_LIMITED | Too many attempts from this network. Wait for Retry-After. |
500 | TOKEN_ | "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:
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
{
"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" }
}-
Show a code screen. Offer the authenticator code, and a way to use a recovery code instead.
-
Send the challenge with exactly one of
code(the 6 digits from the authenticator app) orrecovery_code:BashCouldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
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"}' -
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.
| Answer | Code | What to do |
|---|---|---|
422 | TWO_ | Wrong code. Clear the field and let them try again. |
422 | TWO_ | The 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. |
423 | ACCOUNT_LOCKED | Wrong codes count toward the lockout together with wrong passwords. Show the countdown from errors.. |
403 | UNAUTHORIZED, ACCOUNT_, EMAIL_UNVERIFIED, PASSWORD_ | The same refusals as at sign-in, given only after the right code. |
403 | UNAUTHORIZED, 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_ 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:
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
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.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 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.500TOKEN_: a problem on the server. Keep the tokens and try again later. Don't sign the person out.ISSUANCE_ FAILED
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)
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
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
| Answer | Code | What to do |
|---|---|---|
403 | PASSWORD_ | An 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. |
403 | TWO_ | Your Laramin now requires two-factor authentication. Open errors.enrol_url in the browser so they can set it up. |
403 | UNAUTHORIZED, ACCOUNT_ | API access was turned off, or the account deactivated. |
403 | UNAUTHORIZED, 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
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
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/. Every other device is signed out; the phone that made the change stays signed in.v1/ mobile/ password
Log Out Other Devices in Sessions & devices ends browser sessions only. It doesn't sign anyone out of the app.
Reset a forgotten password
-
Ask for a code. The answer is the same whether or not the address has an account:
HTTPCouldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
POST /api/v1/mobile/password/forgot Content-Type: application/json { "email": "user@example.com" } -
The person receives a 6-digit code by email. It lasts 15 minutes and allows 5 wrong tries.
-
Send the code with the new password:
HTTPCouldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
POST /api/v1/mobile/password/reset Content-Type: application/json { "email": "user@example.com", "code": "482913", "password": "a-new-long-password" } -
On success, take the person to the sign-in screen. No tokens are issued. A wrong, expired or used-up code answers
422with 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
- Social sign-in from a mobile app with Google, Apple and others ends with the same token pair.
- Let people sign up from a mobile app ends with the same token pair once the new account's address is verified.
Thanks. That helps us decide what to write next.
Thanks for telling us what was missing.
You already answered for this article today. Thanks.
We got a lot of answers from your network just now. Try again in a few minutes.
We couldn't send that. Check your connection and try again.
Links in this article
Printed from help.bsscn.com. The online article may have changed since.