Authentication

Precision Normalize uses the OAuth 2.0 client credentials flow. You exchange a client ID and secret for a short-lived JWT, then send that JWT as a bearer token on every request.

Get your credentials

Request a client ID and secret through the IMO Health Developer Portal. You’ll receive:

With an SDK (recommended)

The generated SDKs implement the token exchange and refresh internally. You provide credentials once; the client fetches a token on first use and renews it before expires_in elapses.

import { ImoHealthClient } from "@imo-demo/precision-normalize";
const client = new ImoHealthClient({
  clientId: process.env.IMO_CLIENT_ID!,
  clientSecret: process.env.IMO_CLIENT_SECRET!,
});
// No token handling required — the client manages it.
const session = await client.sessions.create();

The SDKs read these environment variables by default, so you can also construct a client with no arguments:

Manually, over HTTP

curl -X POST https://api-sandbox.imohealth.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "'"$IMO_CLIENT_ID"'",
    "client_secret": "'"$IMO_CLIENT_SECRET"'",
    "audience": "https://api-sandbox.imohealth.com"
  }'

Then send it on each call:

curl -X POST https://api-sandbox.imohealth.com/precision/normalize/v1 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "client_request_id": "demo-001", "requests": [
        { "record_id": "1", "domain": "Problem", "input_term": "chest pain" } ] }'

Scopes

Normalization endpoints require the normalize scope, which is granted automatically to Precision Normalize credentials. The granted scopes come back in the token response’s scope field.

Token errors

POST /oauth/token returns an OAuth-shaped error rather than the standard API error envelope:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed",
  "error_uri": "https://developer.imohealth.com/errors/invalid_client"
}

See Errors and rate limits for the error shape used by the normalization endpoints.