Connections

scalekit_client.connection manages the environment-level connections that AgentKit connectors run on. A connection holds the OAuth app credentials, scopes, and redirect URI Scalekit uses when your users authorize a connector, and one connection serves every user in that environment.

Common path: create the connection once → attach OAuth credentials with update_environment_connection → connect end-user accounts with scalekit_client.actions → run tools.

Most teams create connections in the Scalekit Dashboard — see Configure a connection. Use these methods when you provision or manage environments in code, such as seeding a new environment from a setup script or CI job.

These methods cover environment-level app connections (Flags(is_app=True)). Organization-scoped SSO connection APIs stay on the SaaSKit connection reference.

create_environment_connection

clientConnectionhttps://github.com/scalekit-inc/scalekit-sdk-python/blob/main/scalekit/connection.py

#create_environment_connection

Creates a new environment-level connection. Pass Flags(is_app=True) to register it as an app connection that AgentKit connectors can use.

paramconnectionCreateConnection

CreateConnection object with the provider key and connection type.

paramflagsOptional[Flags]

Optional. Connection flags (is_login, is_app).

returnsCreateConnectionResponse

Create Connection Response

create_connection.py

from scalekit.v1.connections.connections_pb2 import (
    CreateConnection, ConnectionType, Flags
)

# Register the connection at the environment level. is_app=True marks it as an
# app connection, which is what AgentKit connectors resolve against.
response = scalekit_client.connection.create_environment_connection(
    connection=CreateConnection(
        provider_key='HUBSPOT',
        type=ConnectionType.OAUTH,
    ),
    flags=Flags(is_app=True),
)
connection = response[0].connection
print(f"Created: {connection.id}, Key: {connection.key_id}")

list_app_connections

clientConnectionhttps://github.com/scalekit-inc/scalekit-sdk-python/blob/main/scalekit/connection.py

#list_app_connections

Lists environment-level app connections. Filter by provider or search by connection name (key ID) or provider.

parampage_sizeOptional[int]

Results per page (max 30).

parampage_tokenOptional[str]

Optional. Token for pagination.

paramproviderOptional[str]

Optional. Filter by provider (e.g. HUBSPOT).

paramqueryOptional[str]

Optional. Free-text search on connection name (key ID) or provider (3–100 characters).

returnsListAppConnectionsResponse

List App Connections Response

list_connections.py

response = scalekit_client.connection.list_app_connections()

for conn in response[0].connections:
    print(f"Connection: {conn.id}, Provider: {conn.provider_key}")

# Filter by provider
response = scalekit_client.connection.list_app_connections(
    provider='HUBSPOT',
    page_size=10,
)

# Search by connection name or provider
response = scalekit_client.connection.list_app_connections(query='hubspot')

get_environment_connection

clientConnectionhttps://github.com/scalekit-inc/scalekit-sdk-python/blob/main/scalekit/connection.py

#get_environment_connection

Returns an environment-level connection by its id.

paramconnection_idstr

Connection id to retrieve.

returnsGetConnectionResponse

Get Connection Response

get_connection.py

response = scalekit_client.connection.get_environment_connection('conn_123456')
conn = response[0].connection
print(f"Provider: {conn.provider_key}, Type: {conn.type}, Key: {conn.key_id}")

update_environment_connection

clientConnectionhttps://github.com/scalekit-inc/scalekit-sdk-python/blob/main/scalekit/connection.py

#update_environment_connection

Updates an environment-level connection. Use this after create to attach your own OAuth app credentials so users see your brand on the consent screen.

paramconnection_idstr

Connection id to update.

paramconnectionUpdateConnection

UpdateConnection object with fields to update.

returnsUpdateConnectionResponse

Update Connection Response

update_connection.py

import os
from scalekit.v1.connections.connections_pb2 import (
    UpdateConnection, ConnectionType, OAuthConnectionConfig
)

# Read credentials from the environment: a hard-coded client secret leaks to
# anyone with repository access and lets them impersonate your app with the
# provider.
response = scalekit_client.connection.update_environment_connection(
    connection_id='conn_123456',
    connection=UpdateConnection(
        provider_key='HUBSPOT',
        key_id='hubspot-key',
        type=ConnectionType.OAUTH,
        oauth_config=OAuthConnectionConfig(
            client_id={'value': os.environ['HUBSPOT_CLIENT_ID']},
            client_secret={'value': os.environ['HUBSPOT_CLIENT_SECRET']},
        ),
    ),
)
conn = response[0].connection
print(f"Updated: {conn.id}")

Next steps

• Connected accounts — connect end-user accounts and run tools on their behalf
• Configure a connection — create connections in the Scalekit Dashboard