---
description: Onboard REST API — customer integration conventions
globs: "**/*.{ts,tsx,js,jsx,mjs,cjs,py,go,rs,java,kt,rb,php}"
alwaysApply: false
---

# Onboard REST API

When this project integrates with **Onboard**, follow these rules.

## Documentation

- Customer docs: https://docs.onboard.io
- OpenAPI (when available to your environment): `https://rest.onboard.io/openapi.json`

## Authentication

- Send: `Authorization: Token YOUR_API_KEY` (Token scheme, **not** Bearer).
- Keys: https://app.onboard.io/settings/company
- Store keys in env vars or a secrets manager. Never commit keys. Never ship keys to untrusted clients.

## Base URL

- Production REST API is typically `https://rest.onboard.io`.
- Use the base URL your Onboard account was given if it differs (sandbox, etc.).

## Webhooks

- Verify `x-onboard-hmac-sha256` with your subscription secret before acting on payloads.
- Return `2xx` quickly; do heavy work asynchronously.

## HTTP behavior

- Implement pagination per docs (`page`, `page_size`, `max_page_size` where applicable).
- On `429`, back off and retry with jitter.
- Prefer documented paths and fields from the API reference; do not invent enums or payloads.

## Code quality

- Handle non-2xx responses and invalid JSON explicitly.
- Never log full API keys or webhook signing secrets.