Profile Portal login API

Profile Portal exposes the login endpoints its own pages use, so a brand website or app that owns the login form can trigger the same magic link email, email code, or SMS code and finish the login itself. The customer never has to see a Profile Portal page unless you want them to. This is different from the External app magic link, which builds the emailed link on your own app URL and needs a bearer token and a shared secret. The endpoints on this page are the public ones behind the Profile Portal login screen: no credentials, but rate limited and, for browser calls, restricted to allow-listed origins.

Before you start

Requirement	Detail
Base URL	Your Profile Portal domain, for example `https://profile.[brand].com.au`. Every path below is relative to it.
Calling from a browser	Your site’s origin must be allow-listed by Omneo. Requests from any other origin receive `403`. Ask your Omneo account manager to add the origin.
Calling from a server	No allow-listing and no credentials are needed.
Rate limit	5 requests per minute per IP address, per endpoint. Beyond that the endpoint returns `429` with a message you can show the customer.
Existing profiles only	Every request endpoint answers `type: "new"` when no profile matches, and sends nothing. Send those customers to your sign-up flow.
Tenant configuration	Email codes need email code login configured for your tenant, and SMS codes need SMS login configured. See Configuring Profile Portal. Magic links need no extra setup.

How the code flow works

Your site requests a code

The customer enters their email address or mobile number on your site. Your site calls POST /api/auth/email-code or POST /api/auth/sms.

Omneo sends the code

When the profile exists, Omneo issues a 6-digit code and sends it using your configured email template or SMS sender. Nothing is sent for an unknown contact.

Your site verifies the code

The customer enters the code on your site. Your site calls POST /api/auth/code/verify with the code and the same email address or mobile number.

Omneo returns an ID token

Omneo checks the code, invalidates it, and returns a profile-scoped Omneo ID token. Use it to open Profile Portal already logged in, or call the Omneo ID service directly. See Use the token.

Send a magic link

POST /api/auth

Emails the customer a magic link that opens Profile Portal already logged in. The link is valid for about 24 hours.

Body

Field	Required	Description
`email`	Yes	Email address of the profile.
`redirect`	No	Profile Portal path to open after login. Defaults to `/home`.

Other fields accepted by this endpoint are used by Profile Portal’s own pages and are not needed from an external site.

Responses

Status	Meaning
`200`	`{ data: { type: 'existing', id, email, identity, joined_at, first_name } }` when the profile exists; the link is emailed. `{ data: { type: 'new', email } }` when no profile matches.
`400`	Missing `email`.
`429`	Rate limit exceeded.

identity is the customer’s loyalty card number when your tenant has a loyalty card identity configured, otherwise false.

POST /api/auth/email-code

Body

Field	Required	Description
`email`	Yes	Email address of the profile. Matching ignores case and surrounding whitespace.

Responses

Status	Meaning
`200`	`{ data: { type: 'existing', id, email, identity, first_name } }` when the profile exists. A code is emailed, unless one was already sent inside the resend wait, in which case the earlier code stays valid and nothing new is sent. `{ data: { type: 'new', email } }` when no profile matches; no code is issued.
`400`	Missing `email`.
`429`	Rate limit exceeded.
`500`	The code could not be sent. The usual cause is that email code login is not configured for the tenant.

POST /api/auth/sms

Body

Field	Required	Description
`mobile_phone`	Yes	Mobile number as stored on the profile.

Responses

Status	Meaning
`200`	`{ data: { type: 'existing', mobile_phone, identity } }` when the profile exists and a code is sent (or an earlier code is still inside the resend wait). `{ data: { type: 'new', mobile_phone } }` when no profile matches; no code is issued.
`400`	Missing `mobile_phone`.
`429`	Rate limit exceeded.
`500`	The SMS could not be sent.

Verify a code

POST /api/auth/code/verify

Verifies a code from either channel. Send the same identifier the code was requested with.

Body

Field	Required	Description
`code`	Yes	The 6-digit code the customer entered.
`email`	One of	The email address the code was sent to.
`mobile_phone`	One of	The mobile number the code was sent to.

Responses

Status	Meaning
`200`	`{ data: { token, id } }`. `token` is a base64-encoded Omneo ID JWT for the profile and `id` is the profile ID. The code is invalidated.
`400`	Missing fields, or the code is wrong, expired, already used, or was sent to a different email address or mobile number. The response is the same in all of these cases, so show the customer one generic message.
`429`	Rate limit exceeded.
`500`	The code was accepted but a token could not be issued. The code is spent, so ask the customer to request a new one.

POST /api/auth/sms/retrieve is a legacy alias of this endpoint with the same body and responses. Use /api/auth/code/verify for new integrations.

Use the token

The token returned by verify is the same value Profile Portal puts in its own magic links, so you have two options. Open Profile Portal logged in. Redirect the customer to the portal’s login route with the token and an optional path:

https://profile.[brand].com.au/login?token=<token>&redirect=/home

Stay on your site. Base64-decode the token to get the JWT, read its pid (profile ID) and exp (unix expiry) claims, and use the JWT as a bearer token against the Omneo ID service, for example GET https://api.[tenant].getomneo.com/id/api/v1/profiles/me. The steps are the same as validating the ID token on app open. The token is short-lived; to refresh it, mint a new one server-side as described in Using Omneo ID.

Code behaviour

Rule	Value
Format	6 digits
Lifetime	15 minutes from issue
Uses	One. The code is invalidated when it is verified.
Active codes	One per email address or mobile number. Requesting a new code after the resend wait replaces the previous one.
Resend wait	60 seconds by default, configurable per tenant. A request inside the wait returns `200` without sending a new code.
Wrong attempts	5. The code is invalidated on the fifth wrong attempt and the customer must request a new one.
Channels	A code sent by email cannot be verified with a mobile number, and the reverse.

Example

# Request a code by email
curl -s -X POST https://profile.[brand].com.au/api/auth/email-code \
  -H 'Content-Type: application/json' \
  -d '{"email":"customer@example.com"}'

# Verify it
curl -s -X POST https://profile.[brand].com.au/api/auth/code/verify \
  -H 'Content-Type: application/json' \
  -d '{"email":"customer@example.com","code":"123456"}'

The first call returns type: "existing", the second returns { "data": { "token": "<base64-jwt>", "id": "<profile-id>" } }, and repeating the second call returns 400 because the code has been used.

Core setup

Profiles and data

Commerce

Incentives

Reactions

Webhooks and events

Frontend & SDK

Discovery search

POS integration

Appointments

Lists

Groups

Feedback

Extensions

Profile Portal login API

Before you start

How the code flow works

Send a magic link

Body

Responses

Body

Responses

Body

Responses

Verify a code

Body

Responses

Use the token

Code behaviour

Example

​Before you start

​How the code flow works

​Send a magic link

​Body

​Responses

​Send a login code by email

​Body

​Responses

​Send a login code by SMS

​Body

​Responses

​Verify a code

​Body

​Responses

​Use the token

​Code behaviour

​Example

​Related

Before you start

How the code flow works

Send a magic link

Body

Responses

Send a login code by email

Body

Responses

Send a login code by SMS

Body

Responses

Verify a code

Body

Responses

Use the token

Code behaviour

Example

Related