Authentication

Download this guide

The SNH AI Background Check API uses JWT Bearer tokens. Send a valid JWT on protected routes. GET /health is public in standard deployments (Health check).

Getting sandbox access

Contact SNH AI (support@snh-ai.com) to request sandbox access. You receive a Bearer JWT scoped to your account. The token payload must include the tenant claim SNH AI configures for your environment. Without tenant, protected routes reject the request even when the JWT is otherwise valid. Auth0 machine-to-machine tokens sometimes omit tenant unless your identity provider adds it — ask SNH AI to include that claim. Do not commit client IDs, secrets, or sample JWTs into your codebase or docs.

Using the API reference

Open any page under API Reference (for example Create order).
Click Authorize (Bearer lock).
Paste your JWT. You may include the literal Bearer prefix or omit it; use what your tooling expects consistently.
Use the JSON examples as request bodies. Default host is sandbox (https://sandbox.theary.ai) unless you select another server.

Authentication method

Type: Bearer JWT
Header: Authorization: Bearer <jwt_token>

Access is organization-scoped: any valid JWT with your tenant claim can call the documented consumer endpoints for that organization. Role-based permission tiers (for example read-only vs. admin) are not exposed on this API surface.

Making authenticated requests

Include your JWT on protected endpoints (example: List orders).

curl -sS -X GET "https://sandbox.theary.ai/background-check/v1/orders?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"

const response = await fetch('https://sandbox.theary.ai/background-check/v1/orders?page=1&limit=10', {
  headers: {
    Authorization: 'Bearer YOUR_JWT_TOKEN',
    Accept: 'application/json',
  },
})

import requests

headers = {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Accept': 'application/json',
}
response = requests.get(
    'https://sandbox.theary.ai/background-check/v1/orders',
    params={'page': 1, 'limit': 10},
    headers=headers,
)

Production: same paths under https://api.theary.ai with production-issued credentials.

Verify your token (tenant claim)

This decodes the JWT payload without cryptographic verification (useful locally; rely on SNH AI issuance for correctness):

function decodeJwtPayload(jwt) {
  try {
    const payloadPart = jwt.split('.')[1]
    const normalized = payloadPart.replace(/-/g, '+').replace(/_/g, '/')
    const json = Buffer.from(normalized, 'base64').toString('utf8')
    return JSON.parse(json)
  } catch {
    return null
  }
}

const token = process.env.AUTH_TOKEN // or paste a string in REPL
const payload = decodeJwtPayload(token)
if (!payload?.tenant) {
  console.warn('Missing tenant claim — API calls may fail. Ask SNH AI for a token that includes tenant.')
} else {
  console.log(`tenant=${payload.tenant}`)
}

Optional: machine-to-machine (client credentials)

If SNH AI provisions an OAuth client for your integration, you can request tokens from your identity provider with client credentials. Prefer a token that already includes the tenant claim when you test. Never publish secrets.

Security

Organization isolation requires the tenant claim aligned to your SNH AI organization.
Protected routes: all documented integration endpoints except /health require the Bearer JWT.

Troubleshooting

Symptom	What to try
`401 Unauthorized`, empty or generic body	Missing or malformed `Authorization` header; ensure `Bearer <jwt>`.
`401` generic `"Unauthorized"` message	Refresh the JWT or request a new sandbox token from your account manager.
Requests fail after token “works” on `/health`	Decode the JWT and confirm `tenant` is present.
`401` tenant-related failure (missing, unknown, or inactive tenant)	Message is `"Tenant information not found in token"` or `"Tenant validation failed: ..."`; confirm your JWT’s `tenant` claim is present and correct, then contact SNH AI.
Auth0 M2M token without `tenant`	Ask SNH AI to add a `tenant` claim via your IdP Action or use a manually issued JWT.

Testing connectivity then auth

GET /health does not require auth:

curl -sS -i "https://sandbox.theary.ai/health"

const res = await fetch('https://sandbox.theary.ai/health')
const body = await res.json()

import requests

r = requests.get('https://sandbox.theary.ai/health')
body = r.json()

Then call an authenticated endpoint (for example List orders above) with your Bearer token. Expected healthy response:

{
  "success": true,
  "image": "api:stable"
}

Sandbox-specific limits are summarized in Environments.

Error responses

Authentication errors (401)

All token-validation failures (expired, malformed, missing signature, and similar) return the same generic response:

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Tenant resolution errors (401)

Missing, unknown, or inactive tenant information also returns 401, with a more specific message:

{
  "statusCode": 401,
  "message": "Tenant information not found in token"
}

Overview

Platform setup

Authentication

Authentication

Getting sandbox access

Using the API reference

Authentication method

Making authenticated requests

Verify your token (tenant claim)

Optional: machine-to-machine (client credentials)

Security

Troubleshooting

Testing connectivity then auth

Error responses

Authentication errors (401)

Tenant resolution errors (401)

Next steps

​Authentication

​Getting sandbox access

​Using the API reference

​Authentication method

​Making authenticated requests

​Verify your token (tenant claim)

​Optional: machine-to-machine (client credentials)

​Security

​Troubleshooting

​Testing connectivity then auth

​Error responses

​Authentication errors (401)

​Tenant resolution errors (401)

​Next steps

Authentication

Getting sandbox access

Using the API reference

Authentication method

Making authenticated requests

Verify your token (tenant claim)

Optional: machine-to-machine (client credentials)

Security

Troubleshooting

Testing connectivity then auth

Error responses

Authentication errors (401)

Tenant resolution errors (401)

Next steps