Skip to content

OAuth2 Customer Authentication

This guide explains how to authenticate users using OAuth2 in our system. It covers the authorization flow, the use of PKCE (code_challenge), and how to obtain your client credentials.


To use OAuth2, you need a Client ID. You can find or create your API client credentials in the admin panel:

  1. Go to Administration in the backend.
  2. Navigate to Users & Roles.
  3. Click on the Manage dropdown.
  4. Select API Clients.
  5. Here you can view, create, or manage your API clients and obtain the Client ID.

Our API uses the OAuth2 Authorization Code flow with PKCE. This is a secure way to authenticate users, especially for mobile and single-page applications.

This flow means that you will arrive at a WhiteBeard-hosted login page.

Step 1: Generate a Code Verifier and Code Challenge

Section titled “Step 1: Generate a Code Verifier and Code Challenge”

If you are using a public key, the Code Challenge is required. Follow these steps. If you are using a private client, you can skip this step.

  • Code Verifier: A random string (43-128 characters).
  • Code Challenge: A Base64-URL-encoded SHA256 hash of the code verifier.

Example (in PHP):

$codeVerifier = bin2hex(random_bytes(64));
$codeChallenge = rtrim(strtr(base64_encode(hash('sha256', $codeVerifier, true)), '+/', '-_'), '=');

Example (in JavaScript):

async function generateCodeVerifierAndChallenge() {
// Generate a random code verifier (hex string of 64 random bytes → 128 characters)
const randomBytes = new Uint8Array(64);
crypto.getRandomValues(randomBytes);
const codeVerifier = Array.from(randomBytes)
.map(byte => byte.toString(16).padStart(2, '0'))
.join('');
// Hash the code verifier using SHA-256
const encoder = new TextEncoder();
const data = encoder.encode(codeVerifier);
const hashBuffer = await crypto.subtle.digest('SHA-256', data);
// Base64-url encode the hash
const codeChallenge = btoa(String.fromCharCode(...new Uint8Array(hashBuffer)))
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=+$/, '');
return [codeVerifier, codeChallenge];
}

Step 2: Redirect User to the Authorization Endpoint

Section titled “Step 2: Redirect User to the Authorization Endpoint”

Send the user to the /oauth2/authorize endpoint with the following parameters:

  • response_type=code
  • client_id=YOUR_CLIENT_ID
  • redirect_uri=YOUR_CALLBACK_URL
  • code_challenge=CODE_CHALLENGE
  • code_challenge_method=S256
  • scope=... (optional)
  • state=... (recommended for CSRF protection)

Example URL:

https://api.yourdomain.com/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_CALLBACK_URL&code_challenge=CODE_CHALLENGE&code_challenge_method=S256&state=xyz

The user logs in and approves access. They are redirected to your redirect_uri with a code parameter.

Make a POST request to /oauth2/access_token with:

  • grant_type=authorization_code
  • client_id=YOUR_CLIENT_ID
  • redirect_uri=YOUR_CALLBACK_URL
  • code=CODE_FROM_STEP_3
  • code_verifier=YOUR_CODE_VERIFIER

Example (cURL):

curl -X POST https://yourdomain.com/oauth2/access_token \
-d 'grant_type=authorization_code' \
-d 'client_id=YOUR_CLIENT_ID' \
-d 'redirect_uri=YOUR_CALLBACK_URL' \
-d 'code=CODE_FROM_STEP_3' \
-d 'code_verifier=YOUR_CODE_VERIFIER'

The authorization server will respond with a JSON object containing the following properties:

  • token_type with the value Bearer
  • expires_in with an integer representing the TTL of the access token
  • access_token a new JWT signed with the authorization server’s private key
  • refresh_token an encrypted payload that can be used to refresh the access token when it expires.

You can use the less-safe method of username/password-based authentication. In this case, you can set the following values on the /oauth2/access_token request:

  • grant_type=password
  • client_id=YOUR_CLIENT_ID
  • client_secret=CLIENT_SECRET
  • username=CUSTOMER_USERNAME
  • password=CUSTOMER_PASSWORD
  • scope=basic

The authorization server will respond with a JSON object containing the following properties:

  • token_type with the value Bearer
  • expires_in with an integer representing the TTL of the access token
  • access_token a new JWT signed with the authorization server’s private key
  • refresh_token an encrypted payload that can be used to refresh the access token when it expires

You can login users without a password, using a one-time pin (OTP). Follow these steps:

  1. Do a POST /customer/login/request. API reference.
    1. If you are using a confidential/private OAuth2.0 client, you must send the client_password field.
    2. If you are using a public client, follow the same Auth Code flow instructions for generating a code_challenge with code_challenge_method=S256.
  2. If your request body is valid, you will always receive HTTP 200 with {"completed": true} regardless of whether the customer account exists or not, and whether you are rate-limited or not. See the notes below about rate-limiting.
  3. If the e-mail exists in the system, automations with the trigger Customer login request are triggered.
    1. Configure an Automation for this trigger.
    2. Set it to send the customer an e-mail.
    3. Use the macro {{code}} in a text layer to show the code.
  4. Once the user types in the code on your frontend, perform POST /oauth2/access_token. API reference.
    1. The same rules apply for client_secret and code_verifier.
    2. grant_type must be set to otp.
    3. username must be set to the email of the user.
    4. You will receive an access_token and refresh_token if successful.
  • Each e-mail address is rate-limited at 1 login request per minute.
  • OTP login codes are valid for 2 minutes. We aim to increase this to 10 minutes based on customer feedback.
  • A maximum of 5 attempts are allowed for a code. After that, it is destroyed.
  • When a failed attempt occurs, the code is set to expire 1 minute from the current time. Consecutive failed attempts will keep moving the expiry forward by 1 minute to a maximum of 5 attempts or a maximum of 10 minutes of continuous attempts.
  • We plan to add IP-based rate-limiting which will require you to forward the Customer’s IP address in the case of a confidential client.

If a customer registered with send_activation_email=1 (see Customer registration), their account starts out inactive and they receive an activation e-mail containing a code. You can activate the account and log the customer in with a single request — the activation code is consumed on success, so it cannot be replayed.

  1. The customer receives an activation e-mail containing a code (configure the e-mail template via the Customer activation automation trigger, using the {{code}} macro).
  2. Once the user submits the code on your frontend, perform POST /oauth2/access_token. API reference.
    1. The same rules apply for client_secret and PKCE as the other grant types.
    2. grant_type must be set to activation.
    3. username must be set to the email of the user.
    4. code must be set to the activation code.
    5. You will receive an access_token and refresh_token if successful.

Example (cURL):

curl -X POST https://api.yourdomain.com/oauth2/access_token \
-d 'grant_type=activation' \
-d 'client_id=YOUR_CLIENT_ID' \
-d 'username=CUSTOMER_EMAIL' \
-d 'code=ACTIVATION_CODE'

The authorization server will respond with a JSON object containing the following properties:

  • token_type with the value Bearer
  • expires_in with an integer representing the TTL of the access token
  • access_token a new JWT signed with the authorization server’s private key
  • refresh_token an encrypted payload that can be used to refresh the access token when it expires
  • The activation code is single-use: once consumed (successfully or if already active), the same code cannot be used again.
  • If the account is already active, the request fails with an invalid grant error — use one of the other login methods instead.
  • If the code is invalid or expired, the request fails with an invalid grant error. You can resend a new activation e-mail via POST /customer/resend_activation.

5. External authentication (Facebook Login, Google Login, Apple Login)

Section titled “5. External authentication (Facebook Login, Google Login, Apple Login)”

We also support logging in via third-party authenticators. The currently supported providers are:

  • Facebook Login
  • Google Login
  • Apple Login

Your custom setup can also be supported as an authentication backend. Contact our support for more information.

The authentication flow is as follows:

  1. Implement the third-party’s login flow on your application
  2. Redirect the user to login to that provider
  3. On return, read the access token retrieved (or auth code)
  4. Send a POST to /oauth2/access_token with grant_type=password similar to the password-based authentication. In the username field, you would input the name of the provider. You will need a token or auth code to perform the login. This varies based on the provider. Refer to the examples below.

For Facebook login, use the following values:

  • username=facebook
  • password=JSON_STRING

The JSON string must a JSON-encoded object containing:

  • token: Facebook access token
  • source: The login or user registration source. Used typically when a new registration is triggered.

Example:

{"token":"abcxyz", "source":"website"}

For Apple login, use the following values:

  • username=apple
  • password=JSON_STRING

The JSON string must a JSON-encoded object containing:

  • token: Apple JWT access token
  • name: The full name of the user (read upon initial login or sometimes not provided)
  • source: The login or user registration source. Used typically when a new registration is triggered.

Example:

{"token":"abcxyz", "name": "my full name", "source":"website"}

For Google login, use the following values:

  • username=google
  • password=JSON_STRING

The JSON string must a JSON-encoded object containing:

  • token: Google access token
  • source: The login or user registration source. Used typically when a new registration is triggered.

Or if you wish for the system to exchange an auth_code on your behalf, you may provide an auth code:

  • auth_code: Auth code from Google OAuth2 process
  • source: The login or user registration source. Used typically when a new registration is triggered.

Example:

{"token":"abcxyz", "source":"website"}

Customers can add passkeys to their account and log in with them, with no password and no e-mail code. A passkey is stored on the customer’s device (or synced by their password manager) and works with Face ID, Touch ID, Windows Hello or the device PIN.

The examples use @simplewebauthn/browser, which turns the options from the API into a navigator.credentials call and turns the result back into JSON. Any WebAuthn library works, as long as it sends and receives the standard JSON format, with binary fields encoded as base64url.

Passkeys belong to a domain, the relying party ID. Set it under Settings › System › Customer passkey domain. Use your site’s domain without www (for example example.com), so that passkeys work on the site and all its subdomains. If you leave it empty, the site’s domain is used. Changing it later makes existing customer passkeys stop working.

  • Websites must be served over https from that domain or one of its subdomains.
  • iOS apps need an associated domain: add webcredentials:example.com to the app’s entitlements, and serve https://example.com/.well-known/apple-app-site-association with the app’s ID under webcredentials.
  • Android apps need https://example.com/.well-known/assetlinks.json with the delegate_permission/common.get_login_creds relation for the app. Also add the app’s origin, android:apk-key-hash: followed by the base64url SHA-256 hash of its signing certificate, under Other passkey origins.

The .well-known files are served by your front end on that domain, not by the API.

The customer must be logged in. This step needs a full customer token; the limited token from an e-mail link can’t add a passkey.

  1. POST /cms/customer/passkey/register/options with the customer’s token. It returns a challenge_id and options.
  2. Pass options to startRegistration(). The device asks the customer to confirm.
  3. POST /cms/customer/passkey/register with challenge_id, the result as credential, and an optional name (for example the device’s name).
import { startRegistration } from '@simplewebauthn/browser';
const headers = { 'API-Key': API_KEY, 'Authorization': 'Bearer ' + accessToken, 'Content-Type': 'application/json' };
const { challenge_id, options } = await fetch(API + '/cms/customer/passkey/register/options', { method: 'POST', headers }).then(r => r.json());
const credential = await startRegistration({ optionsJSON: options });
const passkey = await fetch(API + '/cms/customer/passkey/register', {
method: 'POST', headers,
body: JSON.stringify({ challenge_id, credential, name: 'My phone' }),
}).then(r => r.json());
  1. POST /cms/customer/passkey/login/options. Send the customer’s e-mail or username as username to offer only their passkeys, or send no username to let the device offer any passkey it has for your site. The second also works with browser autofill.
  2. Pass options to startAuthentication().
  3. POST /oauth2/access_token (form-encoded) with:
    1. grant_type=passkey
    2. client_id, plus client_secret for a confidential client
    3. challenge_id from step 1
    4. credential, the JSON-encoded result of step 2
    5. scope, optional
  4. You receive an access_token and refresh_token, as with the other grants.
import { startAuthentication } from '@simplewebauthn/browser';
const { challenge_id, options } = await fetch(API + '/cms/customer/passkey/login/options', {
method: 'POST',
headers: { 'API-Key': API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({}), // or { username: 'customer@example.com' }
}).then(r => r.json());
const credential = await startAuthentication({ optionsJSON: options });
const tokens = await fetch(API + '/oauth2/access_token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'passkey',
client_id: CLIENT_ID,
challenge_id,
credential: JSON.stringify(credential),
}),
}).then(r => r.json());
  • GET /cms/customer/passkey lists the customer’s passkeys: id, name, created, lastUsed and lastUsedCountry. Key material is never returned.
  • POST /cms/customer/passkey/{passkey_id} with {"name": "..."} renames one.
  • DELETE /cms/customer/passkey/{passkey_id} removes one, so it can no longer log in. The passkey stays on the device until the customer removes it there.

Managing a customer’s passkeys in the CMS

Section titled “Managing a customer’s passkeys in the CMS”

Staff can see and manage a customer’s passkeys, for example when a customer has lost a phone or asks for help logging in.

  1. Go to Revenue › Customers and open the customer.
  2. Click Devices (the phone icon) in the bar on the right.
  3. Open the Passkeys tab. The number next to it is how many passkeys the customer has.

The table shows each passkey’s name, when it was added, and when it was last used to log in, with the country it was used from when that’s known. From the ⋮ menu on a row you can:

  • Rename it, for example to tell two phones apart. If your site or app shows the customer their passkeys, they see the new name there too.
  • Remove it, so it can no longer log in.

Remove all removes every passkey on the account at once, for example when the customer’s devices may be compromised. Removing passkeys doesn’t log the customer out of devices where they’re already logged in; it only stops the passkeys from being used for new logins.

Staff can’t add a passkey for a customer. A passkey is created on the customer’s own device, so the customer adds it from your site or app. A removed passkey stays on the customer’s device until they delete it there, but it no longer works for logging in.

  • A challenge_id is valid for 5 minutes and can be used only once, whether the attempt succeeds or fails. Start again from the options request after a failure.
  • A failed passkey login returns invalid_grant with the hint Invalid passkey. Device limits, and the setting that blocks inactive accounts from logging in, apply the same way as for password login.
  • Asking for login options with a username that doesn’t exist still returns options, so the endpoint can’t be used to find out which accounts exist.
  • A customer can have up to 20 passkeys. Registering the same passkey twice returns PASSKEY_ALREADY_REGISTERED, and the options already list the customer’s existing passkeys so the device can refuse early.
  • Deleting a customer account removes its passkeys.

Include the access token in the Authorization header for API requests:

Authorization: Bearer ACCESS_TOKEN

To get a new access token from a refresh token, send a POST request with following body parameters to /oauth2/access_token:

  • grant_type with the value refresh_token
  • refresh_token with the refresh token
  • client_id with the the client’s ID
  • client_secret with the client’s secret (API Key)
  • scope with a space-delimited list of requested scope permissions. This is optional; if not sent the original scopes will be used, otherwise you can request a reduced set of scopes.

The authorization server will respond with a JSON object containing the following properties:

  • token_type with the value Bearer
  • expires_in with an integer representing the TTL of the access token
  • access_token a new JWT signed with the authorization server’s private key
  • refresh_token an encrypted payload that can be used to refresh the access token when it expires

Example (cURL):

curl -X POST https://api.yourdomain.com/oauth2/access_token \
-d 'grant_type=refresh_token' \
-d 'client_id=YOUR_CLIENT_ID' \
-d 'client_secret=YOUR_CLIENT_SECRET' \
-d 'scope=basic' \
-d 'refresh_token=YOUR_REFRESH_TOKEN'