Add an External Integration

End-to-end developer runbook

1. Step 1 - Confirm the API area: Identify the product area, route module, endpoint path, and consumer before writing or calling code.
2. Step 2 - Read the endpoint contract: Check method, auth, parameters, response, errors, side effects, and related docs.
3. Step 3 - Prepare authentication and input: Use the right session, bearer token, webhook secret, or internal header. Validate body and query data before sending it.
4. Step 4 - Make the request: Call the endpoint from the correct origin and environment. Keep credentials and secrets out of logs.
5. Step 5 - Verify response, side effects, and records: Confirm status code, response shape, database records, external side effects, and audit evidence.
6. Step 6 - Add tests, docs, and handoff notes: Update route inventory, consumer notes, and certification checks before depending on the change.

Workflow

1. Step 1 - Confirm the external integration requirement: Write down caller, route family, records touched, side effects, and consumer.
2. Step 2 - Pick the source module: Reuse an existing route module only when ownership matches; otherwise add a focused module and mount it from src/index.ts.
3. Step 3 - Define auth first: Choose dashboard auth, rego auth, public validation, webhook secret, or internal test control before writing handler logic.
4. Step 4 - Validate inputs: Document path, query, body, file, and header options before consumers call the route.
5. Step 5 - Implement response and error shapes: Return stable JSON or documented binary/redirect behavior.
6. Step 6 - Test side effects: Verify database records and external systems in a safe environment.
7. Step 7 - Regenerate inventory: Run the platform API docs generator and update route reference pages.
8. Step 8 - Add handoff notes: Mention compatibility, migration, deprecation, and monitoring expectations.

Verification checklist

1. Checkpoint 1 - Route appears in generated inventory: Method, path, file, and line number are present.
2. Checkpoint 2 - Auth and role checks are proven: The route has explicit enforcement.
3. Checkpoint 3 - Consumer behavior is tested: Dashboard, rego, LAN, webhook, or integration caller works against the route.
4. Checkpoint 4 - Docs explain operation: A new developer can call, test, and debug the endpoint without source diving first.