Skip to main content
A connection is a stored credential for an outside service, either token for a plain API key or oauth for a consent grant. It lets an agent use the service without the secret ever reaching the model. Matrices holds the secret and attaches it to the request when the tool actually runs, so the model only sees a connection label and a tool result. The API returns metadata only, and tokens are write-only. Every connection has one owner, and the owner decides which agents may use it. A workspace-owned connection serves every agent. An identity-owned one serves only agents carrying that identity, so Dana’s Gmail is invisible to an agent acting for anyone else. The short version is that roles authorize and connections authenticate. A role can allow tool:managed:gmail.* and the call will still fail without an eligible connection, and a connection never widens what a role allowed. Matrices pairs the two at call time based on who is actually calling, not on anything the model wrote. Status is ready, needs_reauth when the grant stopped working, or revoked. Revoking deletes the encrypted secret, then makes one best-effort attempt to revoke it at the provider. Token connections are created straight through the API. OAuth grants start from the dashboard or from the agent itself with connections.connect, since there is no server-to-server connect API yet.
Belongs to a workspace or one identity · Has one provider and kind (token | oauth) · Used by eligible agents only

​
Rules

  • Roles authorize, connections authenticate. You need both. See Rules.
  • Never pass a third-party secret through a prompt, tool input, or memory.
  • Token writes are one-way; rotate with expectedVersion.

​
API

  • GET/POST /v1/connections, PUT /v1/connections/{connectionId}/token, POST /v1/connections/{connectionId}/revoke.
  • Walkthrough: Connect a service.