Agents and integrations
An agent is a named integration record linked to one or more API keys. It can represent a local stdio MCP client, billing service, or scheduled backend job. The record is not a wallet, a separate organization, or an independently isolated on-chain signer. Hosted MCP OAuth connections are managed separately in Settings and do not require an API-key agent record.
Set up an integration#
- Finish onboarding and create complete customers before delegating invoice issuance.
- As the owner, create a named agent with the required scopes and expiry. Agent creation also provisions a key and returns its secret once.
- Configure the trusted service with its key ID and secret. For MCP, follow setup and tool limitations.
- Complete owner-signed server-signer activation if requested. Some Safes must first complete the Safe7579 upgrade flow.
- Verify a read, then explicitly authorize the intended invoice/customer mutations in your application's workflow.
The API supports at most 50 agents per studio. Agent names are at most 64 characters; descriptions at most 256. A management PATCH can change name, description, icon, or active/disabled status. It does not modify a linked key's scopes. Provision a suitable key through the owner management flow when access requirements change.
Understand stop actions#
| Action | What it does |
|---|---|
| Disable agent | HMAC requests from keys linked to the disabled agent are denied. It is a reversible integration-level stop. |
| Re-enable agent | Removes that disabled-agent block. Expired/revoked keys and inactive signers still do not regain validity automatically. |
| Unlink key | Removes the management association. Does not revoke the key, so its credentials may continue working independently. |
| Revoke key | Invalidates that credential's HTTP access. |
| Delete agent | Deletes the record and revokes linked keys. |
| Revoke shared signer | Owner-signed removal of invoice signing authority, affecting associated write access across integrations. |
If you suspect credential compromise, revoke the affected key rather than merely unlinking it. Database-only signer force revocation is not an on-chain removal. See the exact management API actions.
Scope and activity caveats#
Granular scopes are not enforced consistently across legacy API routes. A key attached to a read-only-labeled agent is not a universal read-only sandbox. Give credentials only to trusted services and use endpoint allowlists in those services. The authorization matrix documents actual guards.
This does not give an agent the owner's wallet authority. The server signer supports invoice operations; owner withdrawals need separate valid Safe signatures. Agent names also differ from the on-chain agent address on an invoice, so do not infer per-integration attribution from that address alone.
Key-use activity is sampled at about 10% and logged asynchronously. Dashboard activity and bounded summaries are not complete audit trails. Keep a durable mapping of your business operation, idempotency key, customer UUID, numeric invoice ID, and transaction hashes where applicable.
Reliable automated billing#
For REST issuance, persist the entire payload, including the fixed due timestamp, before sending it with Idempotency-Key. MCP send_invoice anchors the due date to its durable idempotency record: retry with the same idempotency_key and unchanged business inputs. See MCP retry behavior.
Keep email opt-in explicit. Treat pending issuance as pending, not as failure or a shareable result. Preserve returned payment-link tokens. Only confirmed Paid state and verified settlement evidence should drive your application's payment accounting. Production payment webhooks remain planned.