Best Practices

Authentication & tokens#

• Treat the JWT as a short-lived credential; re-authenticate rather than caching it for long periods.
• Hold one token per tenant for multi-tenant integrations — never share a token across tenants.
• Never log tokens. Redact Authorization headers in your own logs.

Governing agents#

• Register agents with honest, minimal capability flags — flags drive risk and define blast radius.
• Use a real owner on every agent and MCP server. Unowned AI is ungovernable.
• Promote through the lifecycle deliberately: DISCOVERED → REGISTERED → APPROVED. Strong auth (MTLS/OAUTH) raises trust.

MCP servers#

• Keep unapproved servers PENDING / UNTRUSTED until reviewed; don't let agents reach unvetted tools.
• Maintain accurate exposedTools — it powers relationships and risk context.

Secrets#

• Never embed long-lived secrets in agent configuration. Store them in a vault and inject at runtime.
• Rotate on a schedule; treat any leaked credential as compromised — revoke, rotate, review the audit trail.

Building on the platform#

• Read /platform/capabilities after sign-in and branch your UI on it — don't hard-code feature availability.
• Branch on the error body, not just the status code (see Errors).
• Build dashboards and alerting on the event stream rather than polling individual resources.
• Generate clients from the OpenAPI spec so you stay in sync as the API evolves.