# Migration guide: Partner API v1

Version 1 is the first stable commercial contract. Integrations built against the legacy clinic-context example should migrate as follows:

- Use `https://sandbox-api.anisivo.com/v1` while developing and `https://api.anisivo.com/v1` in production.
- Exchange the application credential for a 15-minute access token; do not send the client secret to resource endpoints.
- Include the clinic header only for an active, clinic-approved installation.
- Replace broad access with explicit scopes and handle `403`, `409`, `422`, and `429` responses.
- Supply an `Idempotency-Key` for writes and retain webhook delivery IDs for deduplication.
- Verify webhook HMAC against the exact raw request body before parsing JSON.

Breaking changes will ship under a new versioned base path with a dated migration guide and changelog entry.