Set up a connection

A connection is a configuration you create once, in the Scalekit dashboard or with the API. 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).

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.

To create connections from code, for example one per environment or from your own setup script, use the Connections API. This follows the same steps as the dashboard for an OAuth connector: create the connection, register its redirect URI with the provider, then add your OAuth app’s credentials and scopes.

The examples create a Gmail connection named gmail-work. They read your Scalekit API credentials and the Client ID and Client Secret of the OAuth app you registered with Google from a .env file:

SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
SCALEKIT_CLIENT_ID=<your-client-id>
SCALEKIT_CLIENT_SECRET=<your-client-secret>
GMAIL_CLIENT_ID=<google-oauth-client-id>
GMAIL_CLIENT_SECRET=<google-oauth-client-secret>

Install the SDK with pip install scalekit-sdk-python python-dotenv or npm install @scalekit-sdk/node dotenv. Each step below continues the same script. Save the Node.js code in a .mts file, such as connection.mts, and run it with npx tsx connection.mts. The cURL tabs use jq.

1. Create the connection

   Section titled “Create the connection”

   Pass the connector’s identifier, such as GMAIL, and a connection name. The response includes the connection’s redirect URI.

   • Python
   • Node.js
   • cURL

   import os
   from dotenv import load_dotenv
   from scalekit import ScalekitClient
   from scalekit.actions.connections import OAuthSettings
   
   load_dotenv()
   scalekit_client = ScalekitClient(
       env_url=os.environ["SCALEKIT_ENVIRONMENT_URL"],
       client_id=os.environ["SCALEKIT_CLIENT_ID"],
       client_secret=os.environ["SCALEKIT_CLIENT_SECRET"],
   )
   actions = scalekit_client.actions
   
   connection = actions.create_connection(provider="GMAIL", connection_name="gmail-work")
   print("Redirect URI:", connection.oauth.redirect_uri)

   To find a connector’s identifier, call List connectors and read identifier.

2. Register your OAuth app with the provider

   Section titled “Register your OAuth app with the provider”

   In the provider’s developer console, add the redirect URI from step 1 to your OAuth app’s authorized redirect URIs, exactly as returned. Put the app’s Client ID and Client Secret in .env.

3. Add the credentials and scopes

   Section titled “Add the credentials and scopes”

   Update the connection with your OAuth app’s credentials and the scopes your agent needs. Only the fields you send change.

   • Python
   • Node.js
   • cURL

   actions.update_connection(
       "gmail-work",
       oauth=OAuthSettings(
           client_id=os.environ["GMAIL_CLIENT_ID"],
           client_secret=os.environ["GMAIL_CLIENT_SECRET"],
           scopes=["https://www.googleapis.com/auth/gmail.readonly"],
       ),
   )

4. Check it worked

   Section titled “Check it worked”

   Get the connection and confirm it has your Client ID and scopes. The client secret comes back masked.

   • Python
   • Node.js
   • cURL

   connection = actions.get_connection("gmail-work")
   print(connection.connection_name, connection.oauth.client_id, connection.oauth.scopes)

   Expected output: gmail-work, your Client ID and https://www.googleapis.com/auth/gmail.readonly.

To rename, list or delete connections, see the Connections API reference.

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.

Your code refers to a connection by its connection name, the name you gave it in the form. New environments include a GitHub connection named github-connect. Pass it, together with the user’s identifier, when you create a connected account, request an authorization link or execute a tool:

Use the name, not the connection’s conn_... ID. The REST field is called connector, but it also takes the connection name. To see these calls in full, follow Authorize a user, or open Create a connected account and Get an authorization link in the API reference.

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.