Skip to main content

Integrations

Stable public API​

Use documented /api/v1 routes for new integrations. Legacy /api/* session routes are not a public integration contract.

Authentication and scope​

  • Authenticated operations use Authorization: Bearer <JWT> unless their OpenAPI operation explicitly declares another credential.
  • Credentials are scoped. A valid credential can still be rejected when its organization, Program, or operation scope is insufficient.
  • Never put credentials in URLs, browser code, source control, tickets, or logs.

Reliable requests​

  • Send an Idempotency-Key on every mutating public operation; documented authentication bootstrap operations are exempt. Reuse it only when retrying the exact same request.
  • On 429, wait for Retry-After and use exponential backoff with jitter.
  • Use the status code and structured error.code when present; retain X-Request-Id for support.
  • Review the published changelog and OpenAPI diff before deploying an integration change.

Sandbox-safe start​

Use an approved non-production base URL and least-privilege sandbox credentials. A read-only connectivity check needs no token:

curl --fail --silent --show-error "$AIDORBIT_API_BASE/api/health"

Do not use production Volunteer data or credentials in examples, tests, or support artifacts.

See also