Set up a connection

A connection is a configuration you create once in the Scalekit dashboard. It holds everything Scalekit needs to interact with a connector’s API: OAuth app credentials, scopes, redirect URIs, and so on. One connection serves all your users.

Users don’t configure connections. Each user gets a connected account, the per-user record that links them to a connection and holds their tokens. Your code creates it with get_or_create_connected_account, or when it requests an authorization link for the user, and the user activates it by authorizing.

The connection form adapts to what the connector requires. Two things determine how much you need to configure:

• OAuth-based connectors require the most setup. You register an OAuth app with the provider, then enter those credentials into Scalekit.
• Non-OAuth connectors (API key, basic auth, key pairs, and similar) require minimal developer setup (usually just a name). The user provides their own credentials when they create their connected account.

The sections below walk through both patterns.

OAuth connections need an OAuth app registered with the provider. Scalekit provides the Redirect URI; you bring the Client ID and Client Secret. Many connectors also offer Scalekit’s own credentials, so you can skip registration entirely (see the tip at the end of this section).

Already see pre-filled credentials? DCR handled registration for you.

For some connectors, Scalekit automatically completes Dynamic Client Registration (DCR) with the provider. If the Client ID, Client Secret, OAuth Authorization URL, and Token Endpoint fields are already filled in when you open the connection form, DCR was successful — skip steps 2–4 below and go directly to configuring scopes.

If the fields are empty, the provider does not support DCR. Follow the manual registration steps below.

1. Open the connection form

   Section titled “Open the connection form”

   In the Scalekit dashboard, go to AgentKit > Connections and click Add connection. Select the connector you want to configure.

   The form shows the fields that connector requires.

2. Copy the redirect URI

   Section titled “Copy the redirect URI”

   Scalekit generates a Redirect URI for this connection. Copy it; you’ll need it in the next step.

   This URI is where the provider sends the user after they complete the OAuth consent screen. Scalekit handles the callback automatically.

3. Register your OAuth app with the provider

   Section titled “Register your OAuth app with the provider”

   In the provider’s developer console (GitHub, Salesforce, Google, etc.), create an OAuth app and add Scalekit’s Redirect URI to the list of authorized redirect URIs.

   The provider will give you a Client ID and Client Secret after registration.

4. Enter your credentials

   Section titled “Enter your credentials”

   Back in the Scalekit dashboard, enter the Client ID and Client Secret from the provider.

5. Configure scopes

   Section titled “Configure scopes”

   Select the scopes your agent needs. Scopes define what your agent can do on the user’s behalf: for example, user:email or repo for GitHub.

6. Save the connection

   Section titled “Save the connection”

   Click Save. The connection is now active and ready for connected accounts to be created against it.

For connectors that use API keys, basic auth, key pairs, or similar, the connection form asks for very little. In many cases, you only need to give the connection a name.

The user provides their own credentials (their API key, account details, or private key) when they create a connected account. Scalekit collects those credentials through the connected account form and stores them securely.

1. Go to AgentKit > Connections and click Add connection
2. Select the connector
3. Enter a Connection name: this identifies the connection in the dashboard and in your code
4. Click Save

When a connected account is created for this connection, Scalekit presents the user with a form that collects the credentials their specific account requires.

You can create more than one connection for the same connector. This is useful when:

• Different groups of users need different scopes
• You want to maintain separate OAuth apps for staging and production
• You’re integrating with multiple instances of the same service (for example, two different Salesforce orgs)

Each connection has its own name, which you use to identify it in API calls and in the dashboard.

If a user can’t finish connecting, find the error on Troubleshoot connection and OAuth errors:

• failed_to_exchange_token: the page says Authorization failed after the user approved access.
• session_not_found: the page says Session expired or not available.
• redirect_uri_mismatch: the provider rejects the redirect URI.
• It works for your account but fails for your customers: the provider’s OAuth app is still in development or testing.