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.

Omneo ID is a proxy service that issues profile-scoped tokens for front-end use. Instead of exposing a full API token to the browser, your server generates a short-lived ID token scoped to a specific customer profile. The front end uses this token to access profile data via the /profiles/me proxy endpoint.

​
How it works

  1. Your server authenticates with Omneo using a full API token
  2. Your server requests an ID token scoped to a specific profile
  3. The ID token is passed to the front end (e.g., stored in a cookie, metafield, or passed via a template variable)
  4. The front end initialises the Shapes SDK with the ID token
  5. The SDK uses the /profiles/me endpoint to make requests on behalf of that profile

​
Requesting an ID token

Your server makes a POST request to the ID endpoint with the customer’s Omneo profile ID (or an identity handle/value): 
curl -X POST https://api.[tenant].getomneo.com/id/api/v1/auth/token \
  -H "Authorization: Bearer ${SERVER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "9332c9b2-e31c-4d49-8ec3-62a9466d339c"
  }'
Or by identity handle: 
curl -X POST https://api.[tenant].getomneo.com/id/api/v1/auth/token \
  -H "Authorization: Bearer ${SERVER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "1004993MH",
    "id_handle": "magento_id"
  }'
The response includes the ID token to pass to the front end.

​
Anonymous tokens

Omit the id field to generate a token without a profile association. Anonymous tokens can only be used with the /profiles endpoint (to create or upsert a profile) — they cannot access /profiles/me.

​
Using the token in Shopify

The Omneo Shopify plugin stores the ID token in localStorage under the key shapes:omneo:shapestoken:{customer_id}. Check for it first, then generate 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  // hmac_sha256 of customer.id using shop metafield secret
    })
  })
  const data = await response.json()
  token = data.token
  localStorage.setItem(key, token)
}
In Shopify Liquid: 
{% assign customerId = customer.id %}
{% assign customerSignature = customer.id | hmac_sha256: shop.metafields.omneo.id_secret %}

​
The /profiles/me proxy

Once you have an ID token, the SDK uses /profiles/me as a proxy for all profile endpoints. A request to /profiles/me/lists/wishlist internally resolves to /profiles/{profile_id}/lists/wishlist, with the profile ID scoped by the token. This means the browser never sees the raw profile UUID in API calls, and the token cannot be used to access any other profile.

​
Accessing locations via ID proxy

The ID proxy also provides a GET endpoint for locations: 
GET /locations
GET /locations/{id}
Use query parameters to filter, e.g., active stores only: 
GET /locations?filter[is_published]=1&filter[is_permanently_closed]=0