> **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/)

---

# Connected accounts

Connect accounts, start auth, and execute tools with scalekit.actions
<div class="sdk-client-page">

`scalekit.actions` is the primary AgentKit client for connecting end-user accounts, starting OAuth, and executing tools on their behalf.

**Common path:** create or look up a connected account → get an authorization link → verify the user after redirect → run tools.

For raw tool schemas, see [Tool calling](/agentkit/sdks/python/tools/). For exceptions, see [Error handling](/agentkit/sdks/python/errors/).

### get_authorization_link
<div class="sdk-method-section">
  
    
      

      Generates a time-limited OAuth magic link to authorize a user's connection.

      
        User identifier (e.g. email)
      
      
        Connector slug (e.g. gmail)
      
      
        Direct connected account ID (ca_...)
      
      
        Opaque value passed through to the redirect URL
      
      
        App redirect URL for user verification
      
      
        The link.
      

```python wrap showLineNumbers=false
# connection_name + identifier (or connected_account_id)
response = scalekit_client.actions.get_authorization_link(
    connection_name="GMAIL",
    identifier="user@example.com",
)
# response.link, response.expiry
```

    
  
</div>

### verify_connected_account_user
<div class="sdk-method-section">
  
    
      

      Verifies the user after OAuth callback.

      
        Token from the redirect URL query params **Required.**
      
      
        Current user identifier **Required.**
      
      
        Post-verify redirect URL.
      

```python wrap showLineNumbers=false
response = scalekit_client.actions.verify_connected_account_user(
    auth_request_id="opaque-auth-request-id",
    identifier="user@example.com",
)
```

    
  
</div>

### get_or_create_connected_account
<div class="sdk-method-section">
  
    
      

      Fetches an existing connected account or creates one if none exists.

      
        Connector slug **Required.**
      
      
        User\s identifier **Required.**
      
      
        OAuth token or static auth details
      
      
        Organization tenant ID.
      
      
        Your app user ID.
      
      
        Connector-specific options (for example scopes or static.
      
      
        The connected account.id.
      

```python wrap showLineNumbers=false
# authorization_details is optional
response = scalekit_client.actions.get_or_create_connected_account(
    connection_name="GMAIL",
    identifier="user@example.com",
)
# response.connected_account
# Alias: scalekit_client.actions.upsert_connected_account(...)
```

    
  
</div>

### get_connected_account
<div class="sdk-method-section">
  
    
      

      Fetches auth details for a connected account.

      
        Connector slug.
      
      
        End-user or workspace identifier. Use with connection_name.
      
      
        Connected account ID (ca_...) when resolving by ID instead.
      
      
        The connected account.id.
      

```python wrap showLineNumbers=false
# Includes auth credentials (sensitive)
response = scalekit_client.actions.get_connected_account(
    connection_name="GMAIL",
    identifier="user@example.com",
)
# response.connected_account
```

    
  
</div>

### get_connected_account_details
<div class="sdk-method-section">
  
    
      

      Fetches connected account metadata **without** auth credentials.

      
        Connector slug.
      
      
        End-user or workspace identifier. Use with connection_name.
      
      
        Connected account ID (ca_...) when resolving by ID instead.
      
      
        The connected account.id.
      

```python wrap showLineNumbers=false
# Metadata only — no access/refresh tokens
details = scalekit_client.actions.get_connected_account_details(
    connection_name="gmail",
    identifier="user@example.com",
)
print(details.connected_account.status)
```

    
  
</div>

### list_connected_accounts
<div class="sdk-method-section">
  
    
      

      Runs `list_connected_accounts` and returns the result.

      
        Filter by a single connector slug
      
      
        Filter by user identifier
      
      
        Filter by provider
      
      
        Filter to connected accounts belonging to any of these connection names (exact match, max 20 names). Cannot be combined with `connection_name`.
      
      
        Paginated connected accounts.
      

```python wrap showLineNumbers=false
result = scalekit_client.actions.list_connected_accounts(
    connection_names=["GMAIL", "slack"],
    identifier="user@example.com",
)
# result.connected_accounts, result.total_count, result.next_page_token
```

    
  
</div>

### create_connected_account
<div class="sdk-method-section">
  
    
      

      Creates a connected account with explicit auth details.

      
        Connector slug.
      
      
        End-user identifier.
      
      
        Authorization details.
      
      
        Organization tenant ID.
      
      
        Your app user ID.
      
      
        Connector-specific options (for example scopes or static.
      
      
        CreateConnectedAccountResponse.
      

```python wrap showLineNumbers=false
response = scalekit_client.actions.create_connected_account(
    connection_name="GMAIL",
    identifier="user@example.com",
    authorization_details={
        "oauth_token": {
            "access_token": "",
            "refresh_token": "",
            "scopes": [],
        }
    },
)
# response.connected_account
```

    
  
</div>

### update_connected_account
<div class="sdk-method-section">
  
    
      

      Requires `connected_account_id` **or** `connection_name` + `identifier`.

      
        Connector slug.
      
      
        End-user or workspace identifier. Use with connection_name.
      
      
        Connected account ID (ca_...) when updating by ID instead.
      
      
        Replace or merge stored credentials (OAuth tokens, API.
      
      
        Organization tenant ID.
      
      
        Your app user ID.
      
      
        Connector-specific configuration to persist on the account
      
      
        UpdateConnectedAccountResponse.
      

```python wrap showLineNumbers=false
response = scalekit_client.actions.update_connected_account(
    connection_name="GMAIL",
    identifier="user@example.com",
    authorization_details={
        "oauth_token": {
            "access_token": "ya29...",
            "refresh_token": "...",
            "scopes": ["email"],
        }
    },
)
# response.connected_account
```

    
  
</div>

### delete_connected_account
<div class="sdk-method-section">
  
    
      

      Deletes a connected account and revokes its credentials.

      
        Connector slug.
      
      
        End-user or workspace identifier. Use with connection_name.
      
      
        Connected account ID (ca_...) when deleting by ID instead.
      
      
        DeleteConnectedAccountResponse.
      

```python wrap showLineNumbers=false
scalekit_client.actions.delete_connected_account(
    connection_name="GMAIL",
    identifier="user@example.com",
)
```

    
  
</div>

### execute_tool
<div class="sdk-method-section">
  
    
      

      Executes a named tool via Scalekit.

      
        Tool name (e.g. gmail_fetch_emails) **Required.**
      
      
        Parameters the tool expects **Required.**
      
      
        User\s identifier
      
      
        Direct connected account ID
      
      
        Tool result and execution ID.
      

```python wrap showLineNumbers=false
# ActionClient: tool_input first, then tool_name
result = scalekit_client.actions.execute_tool(
    tool_input={"max_results": 1},
    tool_name="gmail_fetch_mails",
    identifier="user@example.com",
)
# result.data, result.execution_id
```

    
  
</div>

### request
<div class="sdk-method-section">
  
    
      

      Makes a REST API call on behalf of a connected account.

      
        Connector slug **Required.**
      
      
        User\s identifier **Required.**
      
      
        API path (e.g. /gmail/v1/users/me/messages) **Required.**
      
      
        HTTP method. Default: GET
      
      
        URL query parameters appended to path
      
      
        JSON-serializable body for POST, PUT, PATCH, or similar.
      
      
        Multipart form fields when the upstream API expects form.
      
      
        Extra HTTP headers merged with Scalekit-injected auth.
      
      
        See return type `requests.Response`.
      

```python wrap showLineNumbers=false
# Proxied HTTP via {env_url}/proxy{path}
response = scalekit_client.actions.request(
    connection_name="GMAIL",
    identifier="user@example.com",
    path="/gmail/v1/users/me/profile",
    method="GET",
)
# requests.Response: response.status_code, response.json()
```

    
  
</div>
</div>


---

## 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 |