Connection

A connection is a signed-in link from your workspace to one outside service in the integration catalog. Its id looks like conn_ plus 16 characters. For the steps, see Connect an outside service. An MCP server is a separate object, managed with the mcp CLI group. An MCP server can point at a connection with --connection-id. Signing in to an MCP server by OAuth also makes a connection. Its integration.id is mcp-server:<id> and its auth kind is mcp_oauth. See Add an MCP server.

States

State	Meaning	Ends here
`pending`	A sign-in started and has not finished.	No
`active`	Signed in. Runs can use it.	No
`expired`	The sign-in no longer works. You can reauthorize it.	No
`revoked`	Access was withdrawn. You can reauthorize it.	No

From	To	Trigger
None	`pending`	Create for an `oauth` or `mcp_oauth` service.
None	`active`	Create for a `none` service, or an `api_key` service with valid key fields.
`pending`	`active`	The person approves access and the provider calls back.
`pending`	`revoked`	The callback’s workspace, user or nonce does not match the pending sign-in.
`pending`	Deleted	`connection revoke`. A pending connection is deleted, not revoked.
`active`	`revoked`	`connection revoke`
`expired` or `revoked`	`pending`	`connection reauthorize` on an OAuth service, or create again with the same service and account label.
`expired` or `revoked`	`active`	Create again for a `none` service, or an `api_key` service with valid key fields.

Create returns the existing connection when one with the same service, owner and account label is already active.

Auth kinds

`authKind`	Sign-in
`none`	No sign-in. Create makes it `active` at once.
`api_key`	You pass key fields. Services with an optional key also report `api_key`.
`oauth`	A person approves access at the provider’s authorize URL.
`mcp_oauth`	OAuth to a remote MCP server.

Setup status

Create and reauthorize return a connection_setup_result. Its status is connected or human_required.

`nextStep.kind`	What to do
`none`	Nothing. The connection is ready.
`oauth_redirect`	Open `nextStep.authorizeUrl` in a browser and approve access.
`api_key_fields`	Send the listed `fields` as `apiKeyFields`.

Fields

The connection, from GET /api/v1/connections/:id:

string

required

Always connection.

string

required

Connection id, conn_ prefix.

object

required

The service it signs in to.

Show integration

string

required

Catalog id, such as linear, or mcp-server:<id>.

string

required

Display name.

string

required

none, api_key, oauth or mcp_oauth.

object

required

Who owns it.

Show owner

string

required

company when the workspace uses it, else user.

string

required

Workspace slug, or the user’s id.

string

required

Workspace name, or the user’s id.

string

required

Your label for the account. May be empty.

string

required

pending, active, expired or revoked.

string[]

required

Scopes the provider granted. May be empty.

string

Last runtime use, ISO 8601. Null when never used.

string

required

ISO 8601.

string

required

ISO 8601.

object

required

Auth facts. Never the secret values.

Show auth

string

required

Same as integration.authKind.

string

Token expiry, ISO 8601. Null when the service has none.

string[]

required

Names of the credential fields held, such as access_token.

string[]

required

mcp, native or both.

object

required

How the token reaches a run. local is device_injection and cloud is network_broker.

GET /api/v1/connections returns rows without auth, availableSurfaces and runtimeDelivery. The list envelope has hasMore, nextCursor, returnedCount and totalCount.

CLI

Command	Does
`connection create`	Start a connection. Needs `--integration-id` and `--owner-type`. Add `--api-key-fields` for a key service.
`connection list`	List connections, newest first. Filter with `--integration`, `--status` or `--q`. Sort with `--sort`.
`connection get <conn_…>`	Show one connection.
`connection reauthorize <conn_…>`	Restart sign-in for an `expired` or `revoked` connection. A person only.
`connection revoke <conn_…>`	Revoke a connection.

pinework connection create --integration-id linear --owner-type company --account-label "Acme Linear"
pinework connection list --status active --sort last_used_desc
pinework connection get conn_7Hq2Lm9Xc4Rt1Bz8
pinework connection reauthorize conn_7Hq2Lm9Xc4Rt1Bz8

API

Method	Path	Does
`GET`	`/api/v1/connections`	List connections you can see. Query: `integration`, `status`, `q`, `sort`, `limit`, `cursor`.
`POST`	`/api/v1/connections`	Start a connection. Body: `integrationId`, `ownerType`, `accountLabel`, `apiKeyFields`. A person only.
`GET`	`/api/v1/connections/:id`	Retrieve one connection.
`POST`	`/api/v1/connections/:id/revoke`	Revoke a connection. Returns `204`.
`POST`	`/api/v1/connections/:id/reauthorize`	Restart sign-in for an `expired` or `revoked` connection. A person only.

You see connections you own and connections linked to the workspace. Others return 404. ownerType is required, but the server does not use it. An agent can list, get and revoke.

Errors

These codes arrive in an error object with code, message and details. That object has no type or requestId.

Code	HTTP	When	What to do
`validation_error`	400	The call has no workspace context.	Sign in to a workspace, or pass one.
`integration_not_found`	404	`integrationId` is not in the catalog.	Check the catalog id.
`connection_not_found`	404	The id is not in your workspace, or you cannot see it.	Check the id with `connection list`.
`connection_owner_mismatch`	403	An agent called create or reauthorize, or the service needs an admin.	Ask a person to run it.
`connection_not_reauthorizable`	409	The connection is `pending` or `active`.	Reauthorize only an `expired` or `revoked` one.
`connection_not_revokable`	400	The revoke could not complete.	Read `message`, then retry.
`api_key_invalid`	400	A required key field is empty or fails the format check.	Pass every field the service lists.
`oauth_exchange_failed`	400	The OAuth setup, token exchange or MCP OAuth discovery failed.	Start the sign-in again.
`unsupported_auth_kind`	400	The service probe failed, or setup hit an internal error.	Retry. Then report it.

See API errors for the shared codes.

Limits

A pending sign-in lasts 10 minutes. After that, start it again.
The OAuth callback takes 10 requests per minute from one IP address.
A list page holds 1 to 100 connections, 25 by default.
q on the list is at most 200 characters.

Connect an outside service

Add an MCP server

Add a server by URL or command, the separate mcp object.

Secret

Store keys that are not tied to a catalog service.

Run

The runs that use a connection’s token.

Start here

Work

Agents

Automate

Connect

States

Auth kinds

Setup status

Fields

CLI

API

Errors

Limits

Connect an outside service

Add an MCP server

Secret

Run

​States

​Auth kinds

​Setup status

​Fields

​CLI

​API

​Errors

​Limits

Connect an outside service

Add an MCP server

Secret

Run

States

Auth kinds

Setup status

Fields

CLI

API

Errors

Limits