> For the complete documentation index, see [llms.txt](https://docs.themochi.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.themochi.app/troubleshooting-and-safety/testing-guide.md).

# Test your integration safely

Start with a read-only test. Receiving an API key does not approve writes, messages, automations, flows, provider connections, or live-customer tests.

## Start with a read-only test

Use a dedicated key for the test organization. Give it only the approved read scopes.

Verify:

1. an authenticated list request succeeds;
2. a missing or invalid key returns `401`;
3. a route outside the key's scopes returns `403`;
4. an unknown or cross-organization resource returns `404`;
5. cursor pagination terminates with `next_cursor: null`;
6. the integration records `X-Request-ID` without logging response data; and
7. the key can be revoked without affecting another integration key.

Use only data the tester is already allowed to access. Do not create test contacts in a live customer organization without that organization's approval.

## Test a write only after approval

Mochi must explicitly approve the organization, scope, endpoint, and test record before a write test.

For each write:

* use a UUID4 `Idempotency-Key`;
* target a reversible, non-critical record;
* retry once with the same key and verify `Idempotent-Replay: true`;
* verify the change appears in Mochi;
* record only the request ID, status, method, path, and timestamp; and
* restore the test record through the documented API or Mochi UI when appropriate.

## Treat messages, automations, flows, and connections separately

Do not test these only because they appear in the API reference. They need an approved organization, key scope, provider account, person responsible for monitoring, and rollback plan. Some operations may remain unavailable during the initial rollout.

Never direct a live outbound test at an unsuspecting lead. Use an approved recipient controlled by the testing organization and agree on the expected message, time window, and rollback before sending.

## Keep a safe test record

Keep a sanitized test record containing:

* organization name and test owner;
* key name or non-secret prefix;
* granted scopes;
* method and path, without sensitive query values;
* UTC timestamp, HTTP status, and `X-Request-ID`;
* expected and observed outcome; and
* rollback or cleanup result.

Never retain the full API key, authorization header, request body containing contact or message data, provider data, or full response data.