> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended**:
> ```bash
> npx @scalekit-inc/cli setup
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for 40+ agents.
> Features: full-stack-auth, agent-auth, mcp-auth, modular-sso, modular-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connections

Manage environment-level AgentKit connections with scalekit_client.connection
<div class="sdk-client-page">

`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`](/agentkit/sdks/python/actions/) → run tools.

Most teams create connections in the Scalekit Dashboard — see [Configure a connection](/agentkit/connections/). 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](/saaskit/sdks/python/connection/).

### create_environment_connection
<div class="sdk-method-section">
  
    
      Creates a new environment-level connection. Pass `Flags(is_app=True)` to register it as an app connection that AgentKit connectors can use.

      
        CreateConnection object with the provider key and connection type.
      
      
        Optional. Connection flags (`is_login`, `is_app`).
      
      
        Create Connection Response
      

```python title="create_connection.py" wrap showLineNumbers=false
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}")
```

    
  
</div>

### list_app_connections
<div class="sdk-method-section">
  
    
      Lists environment-level app connections. Filter by provider or search by connection name (key ID) or provider.

      
        Results per page (max 30).
      
      
        Optional. Token for pagination.
      
      
        Optional. Filter by provider (e.g. `HUBSPOT`).
      
      
        Optional. Free-text search on connection name (key ID) or provider (3–100 characters).
      
      
        List App Connections Response
      

```python title="list_connections.py" wrap showLineNumbers=false
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')
```

    
  
</div>

### get_environment_connection
<div class="sdk-method-section">
  
    
      Returns an environment-level connection by its id.

      
        Connection id to retrieve.
      
      
        Get Connection Response
      

```python title="get_connection.py" wrap showLineNumbers=false
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}")
```

    
  
</div>

### update_environment_connection
<div class="sdk-method-section">
  
    
      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.

      
        Connection id to update.
      
      
        UpdateConnection object with fields to update.
      
      
        Update Connection Response
      

```python title="update_connection.py" wrap showLineNumbers=false

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}")
```

    
  
</div>
</div>

## Next steps

- [Connected accounts](/agentkit/sdks/python/actions/) — connect end-user accounts and run tools on their behalf
- [Configure a connection](/agentkit/connections/) — create connections in the Scalekit Dashboard


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |