Skip to main content
Every Discovery search is authenticated with a search token: a short-lived credential scoped to a specific set of indexes. Mint one from the Omneo API, then use it as the bearer token on search requests.
The Omneo API token used for this call must carry the read-profiles scope. See API tokens for how to create one.

Request body

The body is a rules object mapping each index you want to search to a rule. An empty rule grants unrestricted search on that index.
The resulting token can search only the indexes named in rules. A search against any other index is rejected, so mint a token that covers exactly what the calling application needs and no more.

Response

Scoping a token to a subset of records

A rule can carry a filter, which is applied to every search made with that token. This is how you hand a browser a token that can only see records the signed-in customer is allowed to see.
The filter uses the same syntax as the filter search parameter, described in Running a search. It is enforced on the token, so a client cannot widen it by sending its own filter. The two combine, narrowing the result set further.
For customer-facing applications, scope the token to the signed-in profile. For staff-facing applications such as an in-store lookup tool, an unrestricted rule is usually correct, because staff are expected to search the whole customer base.

Keep minting server-side

Your Omneo API token is a long-lived credential with broad access. Never ship it to a browser, a mobile app, or any other client you do not control.
Mint search tokens from your backend and return only the search token to the client. A common pattern is a small endpoint on your own server, for example GET /api/search-token, that mints a token, caches it, and hands it to the frontend.

Token lifetime and caching

A search token expires 15 minutes after it is issued. The response body carries no expiry field: the expiry is in the token’s exp claim, as Unix seconds. Decode the payload segment to read it rather than hard-coding 15 minutes, so your application keeps working if the lifetime changes. Cache the token and reuse it across searches. Refresh at least 60 seconds before exp so a search already in flight does not fail against a token that expires mid-request. Requests to the Discovery host with a missing, malformed, or expired token are rejected with 401 or 403. Treat either as a signal to mint a fresh token and retry once.

Minting and caching in Node