Schemas

CompleteConnectRequest

The forwarded provider authorization response for a connect flow.

state

string · required

The opaque connect state nonce that resolves the pending connection.

code

string

The provider authorization code, on a successful callback.

error

string

The provider error code, on an error callback (e.g. access_denied).

issueIdentifier

string

The issuer identifier from the authorization response, validated against the one recorded at initiate (RFC 9207).

CompleteConnectResponse

The connection resulting from a completed connect flow.

connectionId

string · required

The connection's id.

redirectUrl

string · required

The fully-built URL to redirect the browser back to: the consumer's validated returnUrl carrying the new connection.

status

string · enum · required

The lifecycle state of a connection.

Enum values:

pending

connected

revoked

expired

Connection

A connection between a principal and a connector.

connectorId

string · required

The connector this connection is to.

createdAt

string · date-time · required

When the connection was created.

id

string · required

The connection's id.

principalId

string · required

The principal the connection is authorized for.

status

string · enum · required

The lifecycle state of a connection.

Enum values:

pending

connected

revoked

expired

updatedAt

string · date-time · required

When the connection last changed.

Connector

A connector available in the catalogue.

callSurface

string · required

The protocol a connection to this connector is called with.

displayName

string · required

Human-readable name shown to the connecting user.

id

string · required

Stable connector identifier, used when initiating a connection.

kind

string · required

The kind of connector.

ConnectorMetadata

Display/merchandising metadata for a connector.

scopes

string[]

The scopes this connector declares; a connect may request a subset.

ConnectorDeveloper

Who publishes the connector; empty when not on file yet.

name

string

The developer's name.

url

string

The developer's homepage.

ConnectorError

string · enum

Enum values:

connection_not_found

ambiguous_connection

connector_not_allowed

return_url_not_allowed

invalid_state

authorization_denied

invalid_request

credential_unavailable

Value of the Sqsp-Connector-Error response header. Present on failures the connector service generates itself; absent on a pass-through response relaying a third party's answer.

ConnectorLinks

Outbound links for a connector's detail view; each empty when not on file.

privacyPolicy

string

The vendor's privacy policy.

support

string

The vendor's support/help center.

website

string

The vendor's homepage.

ConnectorMetadata

Display/merchandising metadata for a connector.

description

string

The connector's one-line description; empty when none is on file yet.

ConnectorDeveloper

Who publishes the connector; empty when not on file yet.

iconUrl

string

The connector's icon; empty when none is on file yet.

ConnectorLinks

Outbound links for a connector's detail view; each empty when not on file.

ErrorResponse

Error body returned by the catalogue and connect operations.

code

string · required

Machine-readable error code returned by the catalogue and connect operations.

errorId

string

Correlation id for a failure the caller cannot act on. Quote it when reporting the error; it appears in the service log alongside the stack trace. Present on unattributable server failures; absent on client errors and on 501.

message

string

Human-readable description, safe to log; never contains secrets.

Grant

A caller permitted to use a connection.

caller

string · required

The permitted caller: the consumer-named agent or service that makes calls through this connection.

Example: agent-runtime

GrantConnectionAccessRequest

The caller to permit on a connection.

caller

string · required

The caller to permit: the consumer-named agent or service that will make calls through this connection.

Example: agent-runtime

InitiateConnectRequest

Request to begin a connect flow for a connector.

connectorId

string · required

The connector to connect, from the catalogue.

returnUrl

string · pattern: (?i)https?://\S+ · required

Where the browser is returned after connecting; validated against the consumer's returnUrl origin allowlist.

connectionId

string · minLength: 0 · maxLength: 36 · pattern: \S+

An existing connection to reconnect in place. Omit to create a new connection.

scopes

string[]

The scopes to request; must be a subset of the connector's declared scopes. Omit to request the connector's declared scopes. An empty array means the same as omitting it — there is no way to request no scopes at all.

InitiateConnectResponse

The authorize URL and the connection id for this flow.

authorizeUrl

string · required

The fully-built provider authorization URL to redirect the browser to.

connectionId

string · required

The connection id; the sole handle for later token resolution.

ListConnectionsResponse

The connections matching the request.

Connection[] · required

The matching connections.

ListConnectorsResponse

The connectors available to the calling consumer.

Connector[] · required

The permitted connectors.

ListGrantsResponse

The callers permitted to use a connection.

Grant[] · required

The grants on the connection.