> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.caresquareapi.com/get-started/authorisation/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.caresquareapi.com/_mcp/server.

# Authorization Guide

Our Public API uses **Bearer token** authentication and a required **X-Plan-Manager-Id** header to scope all requests to a plan manager.

## Obtaining Your API Key

Head to [Settings -> API Keys](https://app.caresquare.com.au/settings?tab=api\&subtab=api-keys) to generate an API Key

## > **Warning**
>
>  Do not share your API key publicly or expose it in client-side code. Treat your API key as a secret and store it securely.Required Headers

Every request to the Public API must include:

| Header                | Description                                                                          |
| --------------------- | ------------------------------------------------------------------------------------ |
| **Authorization**     | `Bearer <your_api_key>`                                                              |
| **X-Plan-Manager-Id** | Plan manager UUID. Must be one of the plan manager IDs associated with your API key. |

## Example Request

```bash
curl -X GET 'https://api.caresquareapi.com/api/public/v1/invoices?limit=20&offset=0' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'X-Plan-Manager-Id: <PLAN_MANAGER_UUID>'
```

## Common Errors

* **401 Unauthorized:** Missing or invalid `Authorization` header (e.g. wrong or expired API key).
* **400 Bad Request:** Missing or invalid `X-Plan-Manager-Id` (e.g. not a valid UUID).
* **403 Forbidden:** Your API key is not allowed to access the requested plan manager (the `X-Plan-Manager-Id` is not in the key’s allowed list).
* **429 Too Many Requests:** Rate limit exceeded. Adding a team member is limited to **one request every 5 seconds per API key**. The `Retry-After` header says how many seconds to wait, and the body uses `error: rate_limited`.