Pairing & credentials

A self-hosted agent pairs exactly like any MCP client: RFC 8414 discovery, RFC 7591 dynamic client registration, then an authorization-code + PKCE flow that its human sponsor approves once in a browser. Request scope offline_access so a refresh token keeps the agent alive unattended.

Declare the RFC 7591 software_id "com.onesilo.agent" at registration — that is the formal signal that classifies the resulting connection as an agent, so it shows up badged and governed like one in the owner's dashboard.

curl -X POST https://api.onesilo.com/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Ops Agent (@ops-bot)",
    "redirect_uris": ["http://127.0.0.1:8765/callback"],
    "software_id": "com.onesilo.agent"
  }'

Identification, never authorization: asserting the agent software_id buys the label and nothing else. Capability comes exclusively from the silo and service grants the owner manages in the dashboard — there are no capability-bearing OAuth scopes to request.

The @onesilo/agent-sdk package implements this whole flow, including endpoint pinning and token persistence; its OAuth client is the reference implementation.

Agents your team runs as services don't have a browser for the consent hop. For those, the owner mints a connection-scoped key from the agent's settings (or the API):

# Owner-authenticated; returns the key exactly once.
curl -X POST https://api.onesilo.com/api/v1/agents/$AGENT_ID/api-key \
  -H "Authorization: Bearer $OWNER_JWT"
# => { "api_key": "sc_..." }

• The key authenticates the agent's own connection at the MCP gateway and the compute endpoint — it inherits every grant, gate, rate limit, and audit surface the agent already has, and nothing more.
• Shown once. Only a hash is stored server-side; treat it like any production secret.
• Rotate by minting again — the previous key stops working immediately. Revoke with DELETE /api/v1/agents/{id}/api-key.
• Suspension cuts access. Disabling an agent (owner or org admin) rejects its key at the door immediately — no waiting for token expiry.

Separate from credentials: a webhook token (aw_…) lets an external system trigger a Silo-hosted agent without holding any owner credential. It authorizes exactly one thing — delivering input to that agent — and is likewise shown once, rotated by re-minting, and revocable. See the transports overview.

A freshly paired agent can do almost nothing — by design. The owner opens the dashboard and grants what this agent should reach: which silos (read-only or read-write, per silo) and which service tools. Every grant is revocable, every change takes effect on the next call, and memory-replacing writes always require the owner's confirmation regardless of grant mode.