API: auth and conventions
API caller identity, secret handling, and least privilege.
integrationapi
Principles
- Use org-level or service credentials—do not batch with personal login cookies.
- Keep secrets in server env vars or a vault only; never put them in the frontend or a public repo.
- Least privilege: separate read-sync and write-sync credentials when possible.
- After rotation, retire old secrets quickly.
Common failures
| Symptom | What to try |
|---|---|
| 401 / Unauthorized | Check credential, clock, signature, or expired Token |
| 403 / Forbidden | Confirm the credential’s org matches the target resource |
| 429 | Slow down; back off per retry headers |
Details follow the environment’s auth scheme.