Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.omneo.io/llms.txt

Use this file to discover all available pages before exploring further.

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:
1

Server holds an admin token

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

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.
3

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.
HelperReturnsUse when
id.auth.isTokenExpired()BooleanChecking whether to mint a fresh token before making a call.
id.auth.getProfileID()The pid claim from the JWTYou need the profile’s UUID without making a network request.
id.reset()voidClearing 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.
MethodPurpose
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.