Developer guide

Authentication model

Everything is authenticated per workspace with short-lived, signed JWTs. A token encodes the workspace and the caller’s role (owner/admin/member), and the server derives what the request is allowed to do from that — never from client-supplied claims. Tokens are short-lived by design; refresh them rather than holding one indefinitely. Org-scoped API keys, which you can mint and revoke, wrap the same model for server-to-server use.

• Every request carries an Authorization: Bearer token scoped to exactly one workspace.
• Authorization is enforced server-side and mirrors the app's roles, so an API caller can never exceed what that role can do in the UI.
• Revoke a leaked key immediately from workspace settings; revocation is effective at once.

Events and webhooks

For asynchronous work, you subscribe to events rather than polling. A representative event delivery is a signed JSON POST to a URL you register:

POST https://your-app.example.com/agentcorp/webhook
X-AgentCorp-Signature: t=...,v1=...
Content-Type: application/json

{
  "type": "task.completed",
  "workspace_id": "ws_1a2b...",
  "data": { "task_id": "tsk_88...", "credits_used": 12 }
}

Verify the signature against your signing secret before trusting a payload, respond 2xx quickly, and do heavy work asynchronously. Useful event types include task lifecycle (task.completed), approvals (approval.requested), and billing signals (credits.low). Treat these names as representative until you receive the versioned spec.

Integration proxy safety

When an agent uses one of your connected tools — Gmail, a CRM, Slack — the call is brokered through AgentCorp’s integration layer rather than exposing raw provider credentials to the model. This matters for a few reasons:

• OAuth tokens for your integrations are stored and used server-side; the model never handles them directly.
• Outbound and sensitive actions are gated by the approval checkpoint before they reach the provider.
• Untrusted content the agent reads (an email body, a web page) is framed defensively to resist prompt-injection attempts that try to hijack the agent.

The practical upshot for integrators: you do not proxy provider credentials yourself, and you can rely on the same approval and isolation guarantees the app provides. See the security guide for the customer-facing view.

Rate limits and idempotency

• Limits are per workspace. On 429, back off exponentially and honor any retry hint.
• Make write requests idempotent (send a client-generated idempotency key) so a retry after a network blip does not double-act.
• Design for the approval delay: a task that needs human confirmation is not a failure — poll or await the corresponding event.

Environments

Develop against a non-production workspace first so test traffic does not touch real inboxes, real contacts, or your production credit balance. Keep separate API keys per environment, never commit them, and rotate on any suspected exposure. Because everything is workspace-scoped, a test workspace is fully isolated from your live one.