Using Omneo ID

The ID client is the customer-facing half of the Omneo SDK. Use it whenever you cannot safely ship an admin token: storefronts, profile portals, in-app customer UIs, and any browser code that needs to read or update a single profile. The full admin client lives separately. See Using the Omneo SDK if you need server-side access to the full API.

How it works

The flow has three steps:

Server holds an admin token

Your backend keeps a long-lived Omneo API token, created in CX Manager.

Server mints a profile-scoped token

Your backend calls id.auth.requestAuthToken({ id }). Omneo returns a short-lived JWT (IDToken) bound to that single profile.

Browser uses the token

Your backend hands the IDToken to the browser, in a cookie, template variable, or theme metafield. Browser code initialises new ID({ tenant, IDToken }) and calls id.profile.* methods. The token only works against the profile it was minted for.

The ID client targets https://api.[tenant].getomneo.com/id/api/v1, a different surface from the admin API.

Server-side: minting the token

Install the SDK and call requestAuthToken from a trusted server. Pass the admin token only at this step.

import { ID } from '@omneo/omneo-sdk'

const id = new ID({
  tenant: '[tenant]',
  omneoAPIToken: process.env.OMNEO_TOKEN
})

const { token } = await id.auth.requestAuthToken({
  id: '9332c9b2-e31c-4d49-8ec3-62a9466d339c'
})

To mint a token by external identity, pass id_handle:

const { token } = await id.auth.requestAuthToken({
  id: '1004993MH',
  id_handle: 'magento_id'
})

The same request as a raw HTTP call, for callers that cannot run Node:

curl -X POST https://api.[tenant].getomneo.com/id/api/v1/auth/token \
  -H "Authorization: Bearer ${OMNEO_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "9332c9b2-e31c-4d49-8ec3-62a9466d339c"
  }'

Anonymous tokens

Omit the id field to mint a token with no profile association. Anonymous tokens can only create or upsert a profile, they cannot read or update an existing one.

const { token } = await id.auth.requestAuthToken({})

Browser-side: using the token

In the browser, initialise the client with the pre-fetched IDToken. Never pass omneoAPIToken here.

import { ID } from '@omneo/omneo-sdk'

const id = new ID({
  tenant: '[tenant]',
  IDToken: window.omneoIDToken
})

const profile = await id.profile.get()

Pass only IDToken to a browser-side ID instance. The omneoAPIToken is the admin bearer token and must stay on a server.

Common operations against the bound profile:

await id.profile.get()
await id.profile.update({ first_name: 'Jane', birth_day: 15, birth_month: 3 })

const transactions = await id.profile.transactions.list({ include: 'product' })
const rewards = await id.profile.rewards.list()
const tiers = await id.profile.tiers.list()

Token helpers

The ID client tracks token expiry internally once a token is set on the constructor or returned by requestAuthToken.

Helper	Returns	Use when
`id.auth.isTokenExpired()`	Boolean	Checking whether to mint a fresh token before making a call.
`id.auth.getProfileID()`	The `pid` claim from the JWT	You need the profile’s UUID without making a network request.
`id.reset()`	void	Clearing the token, for example on logout.

getProfileID() decodes the JWT using Node’s Buffer. In a browser bundle that does not polyfill Buffer (some lean Vite or esbuild setups), this helper throws. The rest of the ID surface is browser-safe.

Profile methods

The id.profile namespace operates on the profile bound to the token. No profile ID is passed.

Method	Purpose
`get()`	Fetch the bound profile.
`update(data)`	Update profile fields.
`delete()`	Soft-delete the profile.
`purge()`	Permanently remove profile data.
`resync()`	Force a resync from connected systems.
`isSubscribed(channel)`, `isUnsubscribed(channel)`	Check comms subscription state.
`subscribe(channel)`, `unsubscribe(channel, opts)`	Update comms subscription state.
`redeem(amount)`	Redeem an amount from the profile’s reward balance.
`updateType(type)`	Change the profile type.
`transactionProducts(params)`	List products from the profile’s transactions.
`Connection(connectionID)`	Accessor for a linked connected profile.

Sub-resources scoped to the bound profile: achievements, addresses, aggregations, attributes, balances, benefits, connections, credits, identities, interactions, ledgers, lists, orders, points, redemptions, regions, rewards, tiers, transactionClaims, transactions. Each sub-resource exposes the same shape as the Omneo client, without the profile ID argument.

Anonymous use: create a profile

With an anonymous token, the only supported action is to create or upsert a profile. The most common pattern is a sign-up form that converts the resulting profile into a logged-in session by minting a fresh, profile-scoped token server-side.

await id.call({
  method: 'POST',
  endpoint: '/profiles',
  body: { first_name: 'Jane', last_name: 'Doe', email: 'jane@example.com' }
})

Locations through the ID API

The ID API exposes a read-only locations endpoint, useful for store finders on a storefront. Call it through id.call():

const locations = await id.call({
  method: 'GET',
  endpoint: '/locations',
  params: {
    'filter[is_published]': 1,
    'filter[is_permanently_closed]': 0
  }
})

A single location:

const location = await id.call({
  method: 'GET',
  endpoint: `/locations/${locationId}`
})

Shopify integration

The Omneo Shopify plugin handles the mint-and-store cycle for you. It stores the IDToken in localStorage under the key shapes:omneo:shapestoken:{customer_id}. The shapes: prefix is a legacy naming artefact, preserved so that already-deployed stores keep working. Read it first, mint a fresh token if missing or expired:

const key = `shapes:omneo:shapestoken:${customerId}`
let token = localStorage.getItem(key)

if (!token) {
  const response = await fetch(`${pluginUrl}/api/v1/auth/token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      id: customerId,
      signature: customerSignature
    })
  })
  const data = await response.json()
  token = data.token
  localStorage.setItem(key, token)
}

const id = new ID({ tenant: '[tenant]', IDToken: token })

customerSignature is the HMAC-SHA256 of the Shopify customer.id, signed with the plugin secret stored in shop metafields. In Liquid:

{% assign customerId = customer.id %}
{% assign customerSignature = customer.id | hmac_sha256: shop.metafields.omneo.id_secret %}

See Shopify authentication for the full flow.

Escape hatch: `id.call()`

Use id.call() for any ID endpoint the SDK does not yet wrap natively. Authentication and base URL are handled for you.

await id.call({
  method: 'GET',
  endpoint: '/profile/balances'
})

The fields are the same as on omneo.call(). See Using the Omneo SDK for the reference.

Core setup

Profiles and data

Commerce

Incentives

Reactions

Webhooks and events

Frontend & SDK

POS integration

Appointments

Lists

Groups

Feedback

Extensions

How it works

Server-side: minting the token

Anonymous tokens

Browser-side: using the token

Token helpers

Profile methods

Anonymous use: create a profile

Locations through the ID API

Shopify integration

Escape hatch: `id.call()`

​How it works

​Server-side: minting the token

​Anonymous tokens

​Browser-side: using the token

​Token helpers

​Profile methods

​Anonymous use: create a profile

​Locations through the ID API

​Shopify integration

​Escape hatch: id.call()

​Related

How it works

Server-side: minting the token

Anonymous tokens

Browser-side: using the token

Token helpers

Profile methods

Anonymous use: create a profile

Locations through the ID API

Shopify integration

Escape hatch: `id.call()`

Related