> ## Documentation Index
> Fetch the complete documentation index at: https://help-loyalife.xoxoday.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with the Loyalife API using OAuth 2.0 client credentials.

## Overview

Loyalife uses **OAuth 2.0 client credentials flow**. You exchange your `client_id` and `client_secret` for a short-lived JWT bearer token. Every subsequent API call must include this token in the `Authorization` header.

```
Authorization: bearer {token}
```

## Getting Your Credentials

Credentials are **per-program** — each loyalty program has its own distinct `client_id` and `client_secret`. To find yours:

1. Log in to the Loyalife Admin portal
2. Navigate to **Configurations → Program Settings → API**
3. Copy the **Client ID** and **Secret ID**

<Note>
  If you need to regenerate credentials (e.g. after a security incident), use the **Reset Client and Secret ID** option on the same page. This immediately invalidates all tokens issued with the previous credentials — update your integration before regenerating.
</Note>

## Token Lifetime

Tokens are valid for **30 minutes** by default. The exact expiry is in the `tokenExpiresOn` field of the auth response. Token lifetime is configurable at the environment level — confirm with your Xoxoday implementation contact if a different value applies.

Your integration should:

1. Cache the token and reuse it across requests until it expires.
2. Proactively refresh before `tokenExpiresOn`, or reactively on receiving a `401`.
3. Never generate a new token per request — this is wasteful and will approach rate limits faster.

## Environments

Both **production** and **staging** environments are available. Contact your Xoxoday implementation contact to get the staging base URL for your program. Test against staging before going live.

## Scopes

The `scope` field is optional. Omit it for a general-purpose program token. To bind a token to a specific member (for member-level operations like OTP login):

```json theme={null}
{
  "scope": "[\"LOGIN\",\"jane.doe@example.com\"]"
}
```

When scope is omitted, the token can be used for all member operations under your program.

## Rate Limits

Rate limits are configurable per `client_id`. The specific limits and the HTTP status returned when exceeded depend on your program configuration — confirm with your Xoxoday implementation contact.

## IP Whitelisting

IP whitelisting is **not required**. The APIs can be called from any server. Always call from a backend server — never expose credentials or make API calls from client-side code (browser or mobile app).

## Error Responses

All APIs return a consistent error structure:

```json theme={null}
{
  "results": {
    "IsSucessful": false,
    "ErrorCode": "1484",
    "ExceptionMessage": "Human-readable reason"
  }
}
```

The API returns actual HTTP status codes alongside this body:

* `401` — Token expired or invalid credentials
* `400` — Malformed or invalid request
* `200` with `IsSucessful: false` — Request was structurally valid but failed business logic (e.g. member not found, OTP mismatch)

Always read `ExceptionMessage` — it is the most reliable field for diagnosing the specific failure.

## Security Notes

<Warning>
  * Never expose `client_secret` or bearer tokens in client-side code, logs, or version control.
  * Always use HTTPS in production.
  * Rotate credentials immediately if compromised — use **Reset Client and Secret ID** in Loyalife Admin.
</Warning>