# Connectors reference

The reference tables behind [Connectors](/platform/connectors): what each provider can do, how tokens are sourced, what a connection carries, and how the surface fails.

## Provider capability matrix

The catalog ships templates prefilled with each provider's endpoints, usual
scopes, and API hosts. What a provider can do differs:

| Provider | Agent tools (MCP) | Inbound events | Notes |
| --- | --- | --- | --- |
| `slack` | Yes — runtime-hosted MCP server inside the task pod | **Yes** — a workspace message can start or continue a task | The only inbound channel today |
| `linear` | Yes — Linear's own hosted MCP endpoint | No — outbound-only; a Linear issue cannot start a task | |
| `gmail` | Yes | No | Credential store; no conversation by design |
| `google_calendar` | Yes | No | Credential store |
| `google_drive` | Yes | No | Credential store |
| `notion` | Yes — via an aggregator-hosted MCP endpoint | No | Credential store |
| `stripe` | Yes | No | Credential store |

A provider outside the catalog works too: supply `authorization_endpoint` and
`token_endpoint` yourself, or pass `issuer` and let the server resolve them from
the issuer's `.well-known` metadata.

Whether a connector must name an answering runtime is derived server-side —
read `connector.requires_runtime` rather than hardcoding the chat providers.

## Authentication modes

`auth_mode` is how the connector's token is sourced, and it is fixed at create:

| Mode | How the token is obtained | Status |
| --- | --- | --- |
| `static` | A long-lived key your org already holds, supplied once | Available |
| `oauth_stored` | Three-legged OAuth; the consented token is stored per connection | Available |
| `person_authorized` | Per-action human approval before each use — see [person-authorized actions](/platform/connectors#person-authorized-actions) | Available |
| `identity_assertion` | The connector's application signs an identity assertion | Accepted into the catalog; not yet served |
| `federated_exchange` | Token exchange against a federated issuer | Accepted into the catalog; not yet served |

## Connection fields

| Field | Meaning |
| --- | --- |
| `subject_type` | `app`, `user`, `workspace`, `federated`, or `person` |
| `status` | `pending_authorization`, `active`, `refresh_failed`, or `revoked` |
| `scopes_granted` | What the provider actually granted, which can be narrower than the connector requested |
| `runtime_group_id` | The runtime answering this connection's channels, for chat providers |
| `token_expires_at` | When the stored token lapses, if the provider sets an expiry |

Access and refresh tokens are never serialized. No read returns them.
`client_secret` and `signing_secret` on the connector are likewise write-only:
accepted on create and update, encrypted at rest, and absent from every read.

## Access and availability

| Operation | Required capability |
| --- | --- |
| List and read connectors and connections; broker a token | `connectors:read` |
| Create and update a connector; mint an install link | `connectors:write` |
| Delete a connector; revoke a connection | `connectors:delete` |

`connectors:delete` is not among the capabilities an API key or application
principal can hold — deleting a connector and revoking a connection are member
operations, from the dashboard or a signed-in CLI session. This matches how
tasks and files treat deletion.

## Error behavior

| Response | When it happens |
| --- | --- |
| `404` `Connectors are not enabled` | Connectors are enabled by default, but a deployment can opt out. When it has, every route on the surface answers this way rather than failing per call. |
| `422` | `runtime` was omitted for a connector whose provider requires one (`requires_runtime`). |
| `409` | The `identity` asserted on `authorize` would mint a `customer` member past the organization's member limit. A conflict rather than a `429`: the cap is a plan limit, not back-pressure. |
| `202` `authorization_pending` | A `person_authorized` action has no approved mission yet; the body carries a mission id and approval URL instead of a token. |

## Related

- [Connectors](/platform/connectors): the concept, setup flow, and `authorize` procedure.
- [MCP tool declarations](/recipes/mcp): the tool-policy gates a connector-backed server passes through.
- [Security](/platform/security): the egress credential boundary.

Connectors reference

The reference tables behind Connectors: what each provider can do, how tokens are sourced, what a connection carries, and how the surface fails.

Provider capability matrix

The catalog ships templates prefilled with each provider’s endpoints, usual scopes, and API hosts. What a provider can do differs:

Provider	Agent tools (MCP)	Inbound events	Notes
`slack`	Yes — runtime-hosted MCP server inside the task pod	Yes — a workspace message can start or continue a task	The only inbound channel today
`linear`	Yes — Linear’s own hosted MCP endpoint	No — outbound-only; a Linear issue cannot start a task
`gmail`	Yes	No	Credential store; no conversation by design
`google_calendar`	Yes	No	Credential store
`google_drive`	Yes	No	Credential store
`notion`	Yes — via an aggregator-hosted MCP endpoint	No	Credential store
`stripe`	Yes	No	Credential store

A provider outside the catalog works too: supply authorization_endpoint and token_endpoint yourself, or pass issuer and let the server resolve them from the issuer’s .well-known metadata.

Whether a connector must name an answering runtime is derived server-side — read connector.requires_runtime rather than hardcoding the chat providers.

Authentication modes

auth_mode is how the connector’s token is sourced, and it is fixed at create:

Mode	How the token is obtained	Status
`static`	A long-lived key your org already holds, supplied once	Available
`oauth_stored`	Three-legged OAuth; the consented token is stored per connection	Available
`person_authorized`	Per-action human approval before each use — see person-authorized actions	Available
`identity_assertion`	The connector’s application signs an identity assertion	Accepted into the catalog; not yet served
`federated_exchange`	Token exchange against a federated issuer	Accepted into the catalog; not yet served

Connection fields

Field	Meaning
`subject_type`	`app`, `user`, `workspace`, `federated`, or `person`
`status`	`pending_authorization`, `active`, `refresh_failed`, or `revoked`
`scopes_granted`	What the provider actually granted, which can be narrower than the connector requested
`runtime_group_id`	The runtime answering this connection’s channels, for chat providers
`token_expires_at`	When the stored token lapses, if the provider sets an expiry

Access and refresh tokens are never serialized. No read returns them. client_secret and signing_secret on the connector are likewise write-only: accepted on create and update, encrypted at rest, and absent from every read.

Access and availability

Operation	Required capability
List and read connectors and connections; broker a token	`connectors:read`
Create and update a connector; mint an install link	`connectors:write`
Delete a connector; revoke a connection	`connectors:delete`

connectors:delete is not among the capabilities an API key or application principal can hold — deleting a connector and revoking a connection are member operations, from the dashboard or a signed-in CLI session. This matches how tasks and files treat deletion.

Error behavior

Response	When it happens
`404` `Connectors are not enabled`	Connectors are enabled by default, but a deployment can opt out. When it has, every route on the surface answers this way rather than failing per call.
`422`	`runtime` was omitted for a connector whose provider requires one (`requires_runtime`).
`409`	The `identity` asserted on `authorize` would mint a `customer` member past the organization’s member limit. A conflict rather than a `429`: the cap is a plan limit, not back-pressure.
`202` `authorization_pending`	A `person_authorized` action has no approved mission yet; the body carries a mission id and approval URL instead of a token.

Connectors: the concept, setup flow, and authorize procedure.
MCP tool declarations: the tool-policy gates a connector-backed server passes through.
Security: the egress credential boundary.