> ## Documentation Index
> Fetch the complete documentation index at: https://docs.matrices.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connections

> Credentials the model never sees.

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](/model/identities), 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](/model/roles) 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.

<Info>
  **Belongs to** a workspace or one identity · **Has one** provider and `kind`
  (`token` | `oauth`) · **Used by** eligible agents only
</Info>

## Rules

* Roles authorize, connections authenticate. You need both. See
  [Rules](/model/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](/guides/connect-a-service).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.