Authentication

Request a machine-to-machine access token and use it safely with the approved OmniLab API endpoints.

2 min read

Your backend exchanges its client credentials for a token, then sends that token with every call.

Before you begin

  • A client_id, client_secret and audience for each environment. They aren't self-service: request them from your Customer Success Manager, and confirm which endpoints are enabled for you.
  • Your API host for each environment, listed in Base URLs and environments.
  • A server you control for the token request, never browser code or a mobile app bundle.

Request a token

  1. Store the production and staging credentials separately, in a secret manager.

  2. Call POST https://<api-host>/v1/oauth:token with a JSON body:

    curl -X POST "https://<api-host>/v1/oauth:token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "YOUR_AUDIENCE",
    "grant_type": "client_credentials"
  }'

  3. Read the token from the response:

    {
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600
}

    expires_in is the token's lifetime in seconds. Asking again while it's valid can return the same token, with the same expires_in. Cache the token, and count its expiry from the first response.

  4. Send the token in the Authorization header on every API request:

    Authorization: Bearer YOUR_ACCESS_TOKEN

When a token request or call fails

ResponseCauseWhat to do
400 on the token requestclient_id or client_secret is missingSend both, then retry
500 on the token requestThe credentials were refused, or no token could be issuedCheck the credentials and audience before you retry
401 on an API callThe token is missing, expired or malformed, or belongs to another account's hostRequest a new token, then retry once

A token only works on the API host of the account it was issued for.

Security rules that matter

  • Never expose the client_secret in browser JavaScript, a kiosk page or a mobile app bundle.
  • Keep the token exchange on your own backend, then call the API server to server.
  • Store separate credentials per environment.
  • Ask your Customer Success Manager to rotate credentials that are compromised or no longer used.
  • Log request IDs and timestamps on your side, but never full secrets or full access tokens.

Next steps

On this page

Before you beginRequest a tokenWhen a token request or call failsSecurity rules that matterNext steps