Skip to main content
POST
Begin authorizing a third-party account connection

Authorizations

Authorization
string
header
required

A Recursion API key, created in the console under API keys.

Path Parameters

provider
string
required

Integration provider id returned by listIntegrationProviders.

Minimum string length: 1

Body

application/json

Optional input for starting or continuing an integration authorization. It may select a provider-defined continuation or an existing connection to re-authorize; organization identity always comes from the authenticated caller.

connection_id
string<uuid>

Existing connection to re-authorize in place, keeping its id and therefore the vault grants that reference it. Omit to create a new connection. The connection must belong to the caller's organization and use this provider; it is recorded server-side against the returned state, never read back from the provider callback.

option
string

Short opaque provider option: either a continuation value returned by a prior completion, or -- for a provider whose catalog entry reports preset_fixed_at_authorization -- the permission preset to authorize (see ProviderInfo.permissions). Omit for a provider needing neither.

Maximum string length: 30

Response

Where to send a user to authorize an integration, plus the one-time state nonce that ties the provider's callback back to this attempt. Returned when an authorization flow is started.

Where to send a user to authorize an integration, plus the one-time state nonce that ties the provider's callback back to this attempt. Returned when an authorization flow is started.

state
string
required

Single-use CSRF nonce identifying this install attempt, not a lifecycle status. The provider must echo it in the callback; completion consumes the server-held record that binds it to the provider, organization, and user.

url
string
required

Absolute provider-hosted authorization page to redirect the user to. Carries the state nonce as a query parameter; send the user here rather than fetching it server-side.