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

# Authenticate with the Partner API

> Pass Client ID and secret as headers or HTTP Basic. Learn canWrite, 401 vs 403, and when to call validate.

Every request needs a **Client ID** and **Client secret**. The practice administrator creates the API client. Credentials are scoped to **one practice**. This API does not use staff passwords or OAuth access tokens.

All traffic is **HTTPS**.

## Get credentials

Ask the administrator for:

* **Client ID** - GUID from OnboardMe practice settings
* **Client secret** - paired secret; rotate it if it leaks

Treat the secret like a password. Do not embed it in a browser app or a public repo.

## Two equivalent methods

<Tabs>
  <Tab title="Headers (recommended)">
    Best for server-to-server integrations.

    ```http theme={null}
    X-OM-Auth-ID: YOUR_CLIENT_ID
    X-OM-Auth-Key: YOUR_CLIENT_SECRET
    ```
  </Tab>

  <Tab title="HTTP Basic">
    Username = Client ID, password = Client secret. Useful in Postman and Swagger **Authorize**.

    ```http theme={null}
    Authorization: Basic BASE64(ClientID:ClientSecret)
    ```
  </Tab>
</Tabs>

Do not mix methods on the same request. Pick one and use it everywhere.

## Validate

Call `GET /api/v1/auth/validate` during setup, after a credential change, or when debugging. **Do not** call it before every other request. It is not a session token endpoint.

```json theme={null}
{
  "authenticated": true,
  "message": "Access granted",
  "clientID": "your-client-id",
  "clientName": "My Integration",
  "canWrite": true,
  "timestamp": "2026-04-16T10:00:00Z"
}
```

<Warning>
  If `canWrite` is `false`, every write route returns **403 Forbidden**. Enable write access on the API client, or keep the integration read-only.
</Warning>

## Auth errors

| Status  | Meaning                                            | What to do                                                                                                           |
| ------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **401** | Missing, wrong, or inactive credentials            | Check ID and secret. Confirm the client is still active. Confirm you are on the [correct region](/concepts/regions). |
| **403** | Credentials work, but the route needs write access | Read `canWrite`. Ask the administrator to allow writes.                                                              |

See also [Errors and rate limits](/errors).

<RequestExample>
  ```bash cURL theme={null}
  curl -sS "https://anzapi.onboardme.app/api/v1/auth/validate" \
    -H "X-OM-Auth-ID: YOUR_CLIENT_ID" \
    -H "X-OM-Auth-Key: YOUR_CLIENT_SECRET"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "authenticated": true,
    "message": "Access granted",
    "clientID": "your-client-id",
    "clientName": "My Integration",
    "canWrite": true,
    "timestamp": "2026-04-16T10:00:00Z"
  }
  ```
</ResponseExample>