Write an agent integration doc security will accept

The requirements doc says the agent will "integrate with the CRM and the billing system." Security review lasts twelve minutes. The reviewer asks who the call acts as, which fields come back, whether a write can fire twice, and how you turn the call off. The doc answers none of those. The review comes back as "insufficient," and the launch date slips a month for a missing table.

This post is the field list reviewers actually ask for, in a template you can paste into the repo. Fill the blanks with method IDs from your machine, not with vendor names.

What gets the doc sent back

Reviewers are not blocking you because the writing is informal. They block you because a vendor name hides the operation. "Salesforce" can mean a read of one Account or an update that changes an owner. Those are different reviews. API compliance for agent integrations walks the control side. The doc is how you show those controls for this project.

A second failure mode is a doc that describes the model and never the runtime. The reviewer needs the allowlist, the policy file path, and what happens on a bad argument. "The model is instructed not to refund" is not a control. A policy that blocks the method is a control.

The checklist before company data is the short pass. The template below is the attachment you leave in the ticket so the next reviewer does not start from zero.

The template

Copy this into docs/agent-integration.md in the repo that holds tooling.json. Replace every angle-bracket note. If you do not know a value, write "unknown" and do not mark the review ready.

# Agent integration requirements

## Owner
Name and team that will merge changes to tooling.json.

## Who the call acts as
The end user, a service account, or a shared bot. One sentence on how they consent.

## Data classes
Customer, employee, payment, or public. Name the fields that come back.

## Methods
IDs copied from `swy list methods` after `swy get`. One per line.
Mark each read or write.
Do not paste a vendor name in place of an ID.

## Writes
For each write: can the provider store an idempotency key.
If it cannot, say the call is not exactly-once.

## Approval
Which writes wait for Slack or Telegram.
Approval starts on Business and Enterprise.
If nobody answers within 48 hours, the call does not run.

## Policy file
Path: .swytchcode/integrations/policies.json
Tests: what `swy policy validate` must pass before merge.

## Logs
Hosted log storage is off until you turn it on.
Retention: 7 days Free, 30 days Pro, 90 days Business.
Local check: `swy audit stats`.

## Credentials
There is no .env file in this project.
Swytchcode keeps credentials in its own local store and reads them when a call runs.
Command: `swy auth connect <provider>`.

## Out of scope
Methods you downloaded and will not enable in this release.

## Rollback
Remove the method ID from tooling.json and merge.

That block is the template. There is no separate download. The copy in git is the one review will diff.

Why these fields are the review

Owner is the person who can merge a method onto the allowlist. A shared inbox fails this line. Who the call acts as is the difference between the end user's token and a bot that can see every record. Data classes tell the privacy review whether this ticket is the one they already run for payments or employee data.

Methods are the whole argument. One ID per line, copied from the CLI, marked read or write. A vendor name in that slot means you have not chosen the operation. Writes need a sentence on idempotency. If the provider does not store a key, say the call can land twice. Approval names the channel and the plan. Slack or Telegram holds exist on Business and Enterprise. A Free or Pro project that lists a hold is describing a feature the plan does not have. The honest line is "this write stays off."

The policy path and the tests give the reviewer a command to rerun. Logs state the retention you actually have: 7 days on Free, 30 on Pro, 90 on Business, and only after storage is turned on. Credentials stay out of the repo. There is no .env file in this project. Swytchcode keeps credentials in its own local store and reads them when a call runs. Out of scope is the list you downloaded and refused. Rollback is the one-line revert: delete the ID from tooling.json and merge.

How to fill the method lines

Run the CLI and paste what it prints. The command reference is the index if a subcommand is unfamiliar.

swy search <provider>
swy get <name from swy search>
swy list methods
swy info <canonical_id from swy list methods>

swy info works after the method is local. If search returns nothing, the requirements doc says the provider is not in the registry and names the owner of the bring-your-own work. Business and Enterprise can add that provider. Do not leave the row as "TBD" with a launch date on top of it.

For a write, say whether the provider stores an idempotency key. If it does not, do not write that the runtime makes the call exactly-once. A retry can land twice. The doc should say that in the Writes section so the reviewer does not have to discover it in production.

What you attach to the ticket

Link the markdown file, the policy tests, and the pull request that enables the first method. A screenshot of a chat is not a substitute. The reviewer will ask what happens if the argument is wrong. The answer is the test swy policy validate already runs.

Mark the review ready only when every method line is an ID you can still find with swy list methods. A renamed bundle that leaves stale IDs in the doc will fail the next review for a reason you could have caught with the command.

Paste the template into the repo, fill the method IDs from swy list methods, and attach that file to the security ticket before you ask for a date.

Related reading

• Policy as code for agent calls. What the Policy file section is pointing at.
• Human approval for a tool call. How the Approval section behaves on a real write.
• API governance tools for AI agents. Where this doc sits next to the allowlist.
• Log every API call an agent makes. How you show the retention line is true.

FAQ

Can I name the vendor and skip method IDs?

You can, and the review will come back. A vendor exposes many operations. The reviewer is signing the operations. Copy them from swy list methods.

What if I do not know whether the provider stores an idempotency key?

Write "unknown" and link the provider's own docs once you have read them. Do not claim exactly-once. Unknown is a reason to keep the write out of the first release.

Does this replace a data protection review?

No. The data class line tells that review where to look. It does not finish it. Payment and employee fields still need the review your company already runs for those classes.

Where should the file live?

Next to .swytchcode/ in the repo that ships the agent. Review diffs the doc in the same pull request as tooling.json. A wiki page nobody updates will drift the week after launch.