Testing Your Integration

Start with a read-only key

Build and verify every read path with a key that holds only *:read scopes. A read-only key cannot mutate anything, and — unless it holds communications:read or audit_log:read, which force request signing — it requires no signing either, which makes the first half of an integration risk-free.

Use a branch-scoped key to limit blast radius

When you move to writes, mint a branch-scoped key pointed at a single branch — ideally a low-volume or internal one. The branch filter is enforced at the gateway, so a bug in your code cannot reach the rest of the company's data.

Note that six resources are company-wide only (storage, inventory, tasks, claims, employees, audit log) — a branch-scoped key gets 403 branch_scope_unsupported there, so those paths need a company-wide key to test.

A pre-flight checklist

• GET /v1/whoami returns the scopes, tenancy, and limits you expect.
• Pagination walks to completion and terminates when next_cursor is absent.
• A deliberately misspelled parameter returns 400 unknown_param — proof your client surfaces errors rather than swallowing them.
• Every write carries an Idempotency-Key — the API rejects writes without one (400 idempotency_key_required) — and a forced retry with the same key produces one record, not two.
• Updates echo the record's updated_at in If-Match, and your conflict handler re-reads on 409 version_conflict.
• Signed requests survive a clock skew test and a body re-serialization pass.
• 429 handling honors Retry-After.
• Webhook signature verification rejects a tampered body.

Verifying webhooks locally

Point a temporary endpoint at a tunnel to your development machine, then fire POST /v1/webhook-endpoints/{id}/test and confirm your verifier accepts the signed ping — and rejects the same body with one byte changed.

A dedicated sandbox

An isolated sandbox environment with seeded data is on the roadmap. Until it ships, the read-only-key and branch-scoped-key approach above is the supported way to build safely. If your integration needs something more, talk to us and we will work through it with you.