Skip to main content

​
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 may reject the request even when the JWT is otherwise valid. In-repo tooling (workflow-test.ts) documents that Auth0 machine-to-machine tokens sometimes omit tenant unless your identity provider adds it. Do not commit client IDs, secrets, or sample JWTs into your codebase or docs.

​
Using the API reference

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

​
Authentication method

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

​
Making authenticated requests

Include your JWT on protected endpoints (example: List orders). 
curl -X GET "https://sandbox.theary.com/background-check/v1/orders?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"
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 Auth0 (or compatible) OAuth client for your integration, obtain tokens via POST {AUTH_DOMAIN}/oauth/token with grant_type, client_id, client_secret, audience. Prefer AUTH_TOKEN (a token that already contains tenant) when testing, per internal workflow tooling. Never publish secrets.

​
Security

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

​
Troubleshooting

SymptomWhat to try
401 Unauthorized, empty or generic bodyMissing or malformed Authorization header; ensure Bearer <jwt>.
401 / message about invalid or expired tokenRefresh the JWT; ask SNH AI for a new sandbox token.
Requests fail after token “works” on /healthDecode the JWT and confirm tenant is present.
403 ForbiddenJWT valid but not allowed for this tenant or operation; contact SNH AI .
Auth0 M2M token without tenantAsk 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 -X GET "https://sandbox.theary.com/health"
Then call an authenticated endpoint (for example List orders above) with your Bearer token. Expected healthy response: 
{
  "success": true,
  "image": "verification-api:latest"
}
Sandbox-specific limits are summarized in Sandbox reference.

​
Error responses

​
Authentication errors (401)

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

​
Invalid token (401)

{
  "statusCode": 401,
  "message": "Invalid or expired token"
}

​
Next steps

  1. Quickstart
  2. Sandbox reference
  3. Demo flow
  4. Create order
  5. API overview