> ## Documentation Index
> Fetch the complete documentation index at: https://docs.billsentry.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Obtain an OAuth2 access token using the client credentials flow.

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 to you at onboarding. No request body is needed — pass your credentials as HTTP Basic Auth only.

```http theme={null}
POST {your_token_url}
Authorization: Basic {base64(client_id:client_secret)}
```

The `Authorization` header value is `Basic ` followed by the Base64 encoding of `{client_id}:{client_secret}` (colon-separated). The grant type and scopes are pre-configured on your M2M client — no body parameters are required.

### Token response

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3a...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

Tokens are valid for approximately **1 hour**. See [Token Lifecycle](/token-lifecycle) for production-ready caching and refresh patterns.

## 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`.

<Info>
  **Maximum body size:** 10 MB.
</Info>