Connect provider accounts

Understand the Koil connection flow before publishing content or subscribing to events.

Start here to connect your customer's provider account, page, channel, or workspace to Koil.

A Connection is created after each successful provider authorization or credential import. Koil stores and refreshes one user's credentials for one external API, then retrieves them at scale for provider operations without your product passing raw credentials at request time.

Koil setup has two parts. First, create a Connection so Koil can manage provider authorization and credential refresh. Then, create a Connected Profile so Koil knows which provider profile to use for API operations.

Why both?

A Connection represents the credential grant: who authorized access, which provider app was used, which scopes are available, and whether Koil can retrieve fresh credentials when an operation runs. A Connected Profile represents the publishing or event target. One authorized user may be able to post to multiple pages, channels, or workspaces, so Koil asks you to choose the exact profile before publishing or subscribing to events.

The flow

Create a Connection. Use Koil-hosted OAuth for new user authorization, or import existing credentials if you already have a refreshable provider grant.
Create a Connected Profile. Choose the specific provider profile, page, channel, location, or account Koil should use.
Check capabilities. Capabilities tell you which content types and operations the Connected Profile supports.
Choose what to build next. Use the same connectedProfileId to publish content or subscribe to events.

Key terms

Connection: the Koil-managed credential grant for one user's access to one provider API.
Connected Profile: the provider profile Koil can access through one Connection.
connectedProfileId: the ID you send with publish, event, read, and reply calls.
contentType: the provider content collection, such as instagram.media.items.
variant: a provider-specific operation shape, such as feed or reel.
capabilities: the operations and event types a Connected Profile supports.

Create a Connection

Use Koil-hosted OAuth when your users need to authorize a provider account from your product. Koil creates a short-lived Connect Session and returns the provider approval URL.

Create a Connect Session. POST /v1/connect/sessions
Redirect your user to the returned authorizationUrl.
The user approves access with the provider.
Wait for the connect_session.completed event, or check the session status. GET /v1/connect/sessions/{connectSessionToken}
Store the returned connectionId.

The connectionId is the durable handle for credentials Koil stores, refreshes, and resolves when a Connected Profile operation runs.

Use credential import when your product already has a provider grant.

Import the provider grant. POST /v1/connections/import
Koil stores the credential material securely.
Store the returned connectionId.
Use Koil resource IDs for future calls instead of sending provider credentials again.

Create a Connected Profile

A Connected Profile is the provider profile Koil can access through one Connection. Most Koil operations start with a connectedProfileId.

List provider profiles available through the Connection. GET /v1/connections/{connectionId}/eligible-profiles
Let your customer or application choose the profile to use.
Create a Connected Profile. POST /v1/connected-profiles
Store the returned connectedProfileId.
Check which operations it supports. GET /v1/connected-profiles/{connectedProfileId}/capabilities

Two users can authorize the same provider profile. Koil keeps those Connected Profiles separate by storing the selected provider profile together with the connectionId, so your product can choose the right actor for each action.

Next steps

After setup, branch into publishing for outbound content or event subscriptions for inbound content. To reply to provider content, set up events first, then use reply to content from the received event.