Configure 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. When a user authenticates, Scalekit creates a connected account, the per-user record that links their identity to a connection and holds their tokens.

What the connection form asks for

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.

Set up an OAuth connection

OAuth connections require you to create an OAuth app with the provider and link it to Scalekit. Scalekit provides the Redirect URI; you bring the Client ID and Client Secret.

1. 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

   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.

   Localhost redirect URIs work in staging

   For development and staging, you can run your MCP server on localhost. Register a localhost URL (for example, http://localhost:3000/callback) as the redirect URI in the provider’s console. The MCP client must be able to reach the server — typically both run on the same machine during local testing.

3. 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.

   Redirect URI must match exactly

   The URI in the provider’s console must match what Scalekit shows character-for-character, including trailing slashes. A mismatch causes the OAuth flow to fail with a redirect_uri_mismatch error.

4. Enter your credentials

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

5. Configure scopes

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

   Scopes apply to all connected accounts

   The scopes you set here apply to every connected account that uses this connection. If you need different scopes for different user groups, create separate connections for each group.

6. Save the connection

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

Use Scalekit credentials to get started faster

For some connectors, Scalekit offers a Use Scalekit credentials option. This lets you skip the OAuth app registration step and start testing immediately. Switch to your own credentials before going to production. See Bring your own credentials.

Set up a non-OAuth connection

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.

Create multiple connections for the same connector

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.

Common scenarios

Why am I seeing a failed_to_exchange_token error after the consent screen?

This error means the OAuth token exchange failed after the user completed the provider’s consent screen. The error description may include Error executing post-auth hooks.

Common causes: the verification session timed out because you waited too long to complete consent, a transient platform issue during the token exchange, or a network interruption between the provider and Scalekit.

What to try:

1. Close the error page and restart the connection flow
2. If the error persists, check the Scalekit status page for ongoing incidents
3. If no incident is reported, contact support with the full error URL and timestamp

An error that resolves on retry is almost always transient. If it fails consistently for the same connection, check your OAuth app credentials and redirect URI configuration.

Why does the callback page say “session expired or invalid”?

The OAuth verification session has a time limit. If you take too long to complete authentication with the provider (for example, you step away mid-flow or the consent screen loads slowly), the session expires before the callback arrives.

Close the window and start the connection flow again. No configuration change is needed.

Why am I getting a redirect_uri_mismatch error?

The redirect URI registered in the provider’s OAuth app does not match the URI that Scalekit sends in the authorization request. Providers enforce an exact string match.

1. In Scalekit Dashboard, go to AgentKit > Connections and open the affected connection
2. Copy the Redirect URI shown in the connection form
3. In the provider’s developer console, verify the URI matches exactly — including protocol (https vs http), trailing slashes, and port numbers
4. Save and retry the connection flow

Common mismatches: a trailing slash (/callback/ vs /callback), http vs https, or a missing port number.