Authentication

The BillSentry API uses the OAuth2 client_credentials flow for M2M (machine-to-machine) authentication. Your system exchanges a Client ID and Client Secret for a short-lived JWT access token.

Obtain an access token

Make a POST request to the Token URL provided at onboarding. Recommended: HTTP Basic Auth for credentials, with a form body that includes grant_type. scope is optional and only needed if your tenant’s API gateway is configured to require a specific scope.

POST {your_token_url}
Authorization: Basic {base64(client_id:client_secret)}
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

If your onboarding instructions include a scope, append it to the form body. Scopes are customer-specific and typically follow the form billreview:<CustomerScope> (for example, billreview:write):

POST {your_token_url}
Authorization: Basic {base64(client_id:client_secret)}
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=billreview:<CustomerScope>

Part	Value
`Authorization`	`Basic` + Base64 of `{client_id}:{client_secret}`
`grant_type`	`client_credentials` (required)
`scope`	Optional. Customer-specific scope, e.g. `billreview:<CustomerScope>`. Use it only if your onboarding instructions provide one.

scope is optional by default. If your onboarding instructions include a scope, use that value.

Alternate: credentials in the body

Some HTTP clients prefer putting credentials in the form body instead of Basic Auth. If your onboarding instructions do not include a scope, omit the &scope=... line.

POST {your_token_url}
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={your_client_id}
&client_secret={your_client_secret}
&scope=billreview:<CustomerScope>

Token response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3a...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Tokens are valid for approximately 1 hour. See Token Lifecycle for production-ready caching and refresh patterns.

Using the token on API calls

Every BillReview API request requires both headers:

Authorization: Bearer {access_token}
x-api-key: {your_api_key}

The API key selects your tenant and environment (sandbox vs production). Use the sandbox API key with sandbox M2M credentials, and the production API key with production M2M credentials. Mixing them returns 403.

Compression

Request bodies may be sent as plain JSON or gzip-compressed JSON. Gzip is recommended for large payloads (many service lines) to reduce bandwidth and latency. Plain JSON (simplest — works in Postman and all HTTP clients):

Content-Type: application/json

Gzip-compressed (recommended for production at volume):

Content-Type: application/json
Content-Encoding: gzip

When Content-Encoding: gzip is present, the body must be the gzip-compressed bytes of a valid JSON object. Content-Type remains application/json regardless — it describes the underlying data format, not the transport encoding. Responses from the API are always gzip-compressed. Most HTTP clients (including Postman, curl with --compressed, and all common HTTP libraries) decompress responses automatically when they send Accept-Encoding: gzip.

Maximum body size: 10 MB.Exception: POST /v1/facility accepts plain JSON only — do not gzip that endpoint.

Getting Started

API Reference

Production Guide

Resources

Obtain an access token

Alternate: credentials in the body

Token response

Using the token on API calls

Compression

​Obtain an access token

​Alternate: credentials in the body

​Token response

​Using the token on API calls

​Compression

Obtain an access token

Alternate: credentials in the body

Token response

Using the token on API calls

Compression