Skip to content

docs(actions): describe identifier and connection_name the way the guides do #210

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ravibits wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs(actions): describe identifier and connection_name the way the guides do #210

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
63cc5ff
docs(actions): describe identifier and connection_name the way the gu…
claude Sep 27, 2026
ec69ac2
docs(actions): finish the identifier and connection wording
claude Sep 28, 2026
be480b6
Merge remote-tracking branch 'origin/main' into docs/agentkit-docstrings
Oct 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 75 additions & 41 deletions scalekit/actions/actions.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,9 +132,14 @@ def execute_tool(
Account resolution (one of the following combinations is required):
connected_account_id: ID of the connected account to use. Provide this
OR the (identifier + connection_name) pair — not both.
identifier + connection_name: Resolve the connected account by user
identifier (e.g. a user ID or email) together with the connection
name (e.g. 'slack-b1fqL2Dr', 'notion-arffP5Ff').
identifier: Your app's ID for the user, the same value you use when the user
connects. Use a stable internal ID, not an email address. Pass it with
``connection_name``.
connection_name: Connection name, as shown in AgentKit > Connections (for
example ``gmail``). Pass it with ``identifier``.

The connected account must be ``ACTIVE``. Otherwise the call fails with
``INVALID_ARGUMENT``; send the user an authorization link first.

Returns:
ExecuteToolResponse containing execution results
Expand Down Expand Up @@ -193,9 +198,11 @@ def list_tools(

Thin wrapper around ToolsClient.list_tools.

:param connection_name: Filter by connector identifier, e.g. 'github-connect' (optional)
:param connection_name: Connection name, as shown in AgentKit > Connections (for
example ``gmail``) (optional)
:type: str
:param identifier: Filter/resolve by connected-account identifier (optional)
:param identifier: Your app's ID for the user, the same value you use when the
user connects. Use a stable internal ID, not an email address (optional)
:type: str
:param provider: Filter by provider key, e.g. 'github' (optional)
:type: str
Expand Down Expand Up @@ -260,11 +267,14 @@ def get_authorization_link(
**kwargs
) -> MagicLinkResponse:
"""
Get authorization magic link for a connected account
Get an authorization link for a connected account. Send it to the user so
they can connect their account, or reconnect it after it expires.

:param connection_name: Connector identifier
:param connection_name: Connection name, as shown in AgentKit > Connections (for
example ``gmail``)
:type: str
:param identifier: Connected account identifier
:param identifier: Your app's ID for the user, the same value you use when the
user connects. Use a stable internal ID, not an email address
:type: str
:param connected_account_id: Connected account ID (optional)
:type: str
Expand Down Expand Up @@ -302,7 +312,9 @@ def verify_connected_account_user(
:param auth_request_id: Auth request ID as base64url-encoded opaque token from the
user verify redirect URL query params
:type: str
:param identifier: Current logged in user's connected account identifier
:param identifier: Your app's ID for the signed-in user, the same value you used
when you created the authorization link. Use a stable internal ID, not an
email address
:type: str

:returns:
Expand Down Expand Up @@ -333,14 +345,18 @@ def list_connected_accounts(
"""List connected accounts with optional filtering.

Args:
connection_name: Filter by a single connector slug, e.g. ``"github"``.
connection_name: Filter by one connection. Connection name, as shown in
AgentKit > Connections (for example ``gmail``).
Mapped to the ``connector`` field in the underlying request.
identifier: Filter by end-user identifier, e.g. email or opaque user ID.
provider: Filter by OAuth/API-key provider slug, e.g. ``"google"``.
connection_names: Filter results to connected accounts belonging to *any*
of these connection slugs. Useful when you want to check multiple
connectors at once, e.g. ``["github", "google-calendar", "slack"]``.
Can be combined with ``identifier`` to narrow results to a specific user.
identifier: Filter by user. Your app's ID for the user, the same value you
use when the user connects. Use a stable internal ID, not an email
address.
provider: Filter by provider key, e.g. ``"google"``.
connection_names: Filter to connected accounts in *any* of these
connections, by connection name as shown in AgentKit > Connections,
e.g. ``["github", "google-calendar", "slack"]``. Takes up to 20 names and
can't be combined with ``connection_name``. Combine it with
``identifier`` to check one user's accounts across several connections.

Returns:
ListConnectedAccountsResponse containing the matching connected accounts.
Expand All @@ -363,9 +379,12 @@ def delete_connected_account(
"""
Delete a connected account

:param connection_name: Connector identifier (required)
:param connection_name: Connection name, as shown in AgentKit > Connections (for
example ``gmail``). Required unless you pass ``connected_account_id``
:type: str
:param identifier: Connected account identifier (required)
:param identifier: Your app's ID for the user, the same value you use when the
user connects. Use a stable internal ID, not an email address. Required
unless you pass ``connected_account_id``
:type: str
:param connected_account_id: Connected account ID (optional)
:type: str
Expand Down Expand Up @@ -395,11 +414,14 @@ def get_connected_account(
**kwargs
) -> GetConnectedAccountAuthResponse:
"""
Get connected account authorization details by identifier
Get a connected account, including its credentials and status.

:param connection_name: Connector identifier (required)
:param connection_name: Connection name, as shown in AgentKit > Connections (for
example ``gmail``). Required unless you pass ``connected_account_id``
:type: str
:param identifier: Connected account identifier (required)
:param identifier: Your app's ID for the user, the same value you use when the
user connects. Use a stable internal ID, not an email address. Required
unless you pass ``connected_account_id``
:type: str
:param connected_account_id: Connected account ID (optional)
:type: str
Expand Down Expand Up @@ -440,15 +462,17 @@ def get_connected_account_details(
You must provide **one** of the following to identify the connected account:

- ``connection_name`` **and** ``identifier`` — use when you know the
connector name and the end-user's identifier (e.g. email address).
connection name and your app's ID for the user.
- ``connected_account_id`` — use when you already hold the Scalekit
connected account ID.

:param connection_name: Connector identifier, e.g. ``"salesforce-1hpnGzcD"``.
:param connection_name: Connection name, as shown in AgentKit > Connections (for
example ``gmail``).
Required when ``connected_account_id`` is not provided.
:type connection_name: str
:param identifier: End-user identifier tied to the connected account,
e.g. ``"john.doe"``. Required when ``connected_account_id`` is not provided.
:param identifier: Your app's ID for the user, the same value you use when the
user connects. Use a stable internal ID, not an email address.
Required when ``connected_account_id`` is not provided.
:type identifier: str
:param connected_account_id: Scalekit connected account ID. When supplied,
``connection_name`` and ``identifier`` are ignored.
Expand Down Expand Up @@ -533,9 +557,11 @@ def request(
"""
Make a proxied REST API call through Scalekit on behalf of a connected account.

:param connection_name: Connector identifier (required)
:param connection_name: Connection name, as shown in AgentKit > Connections (for
example ``gmail``) (required)
:type connection_name: str
:param identifier: Connected account identifier (required)
:param identifier: Your app's ID for the user, the same value you use when the
user connects. Use a stable internal ID, not an email address (required)
:type identifier: str
:param path: API path to call, e.g. "/v1.0/me/messages" (required)
:type path: str
Expand Down Expand Up @@ -778,9 +804,11 @@ def create_connected_account(
"""
Create a new connected account

:param connection_name: Connector identifier (required)
:param connection_name: Connection name, as shown in AgentKit > Connections (for
example ``gmail``) (required)
:type: str
:param identifier: Connected account identifier (required)
:param identifier: Your app's ID for the user, the same value you use when the
user connects. Use a stable internal ID, not an email address (required)
:type: str
:param authorization_details: Authorization details (OAuth token or static auth) (optional)
:type: Optional[Dict[str, Any]]
Expand Down Expand Up @@ -841,9 +869,11 @@ def get_or_create_connected_account(
"""
Get an existing connected account or create a new one if it doesn't exist

:param connection_name: Connector identifier (required)
:param connection_name: Connection name, as shown in AgentKit > Connections (for
example ``gmail``) (required)
:type: str
:param identifier: Connected account identifier (required)
:param identifier: Your app's ID for the user, the same value you use when the
user connects. Use a stable internal ID, not an email address (required)
:type: str
:param authorization_details: Authorization details (OAuth token or static auth) (optional)
:type: Optional[Dict[str, Any]]
Expand Down Expand Up @@ -914,9 +944,11 @@ def update_connected_account(
"""
Update an existing connected account

:param connection_name: Connector identifier (required)
:param connection_name: Connection name, as shown in AgentKit > Connections (for
example ``gmail``) (required)
:type: str
:param identifier: Connected account identifier (required)
:param identifier: Your app's ID for the user, the same value you use when the
user connects. Use a stable internal ID, not an email address (required)
:type: str
:param authorization_details: Authorization details (OAuth token or static auth) (optional)
:type: Optional[Dict[str, Any]]
Expand Down Expand Up @@ -1297,9 +1329,10 @@ def list_mcp_connected_accounts(
Args:
config_id: Scalekit ID of the MCP configuration to inspect,
e.g. ``"cfg_01abc123"``.
identifier: End-user identifier for whom to fetch auth state — usually
an email address or opaque user ID that was used when calling
``ensure_instance``, e.g. ``"alice@example.com"``.
identifier: The user to fetch auth state for. Your app's ID for the user,
the same value you use when the user connects. Use a stable internal ID,
not an email address,
the same one used when calling ``ensure_instance``, e.g. ``"user_123"``.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
include_auth_link: When ``True``, every connected account in the response
will include an ``authentication_link`` regardless of its current
status. Set this to ``True`` when building a connected-account
Expand Down Expand Up @@ -1337,7 +1370,7 @@ def list_mcp_connected_accounts(

state = client.actions.mcp.list_mcp_connected_accounts(
config_id="cfg_01abc123",
identifier="alice@example.com",
identifier="user_123",
include_auth_link=True,
)
for account in state.connected_accounts:
Expand Down Expand Up @@ -1373,9 +1406,10 @@ def create_session_token(
Args:
mcp_config_id: Scalekit ID of the MCP configuration the token should
grant access to, e.g. ``"cfg_01abc123"``.
identifier: End-user identifier for whom the token is minted — typically
the same email or opaque ID used when calling ``ensure_instance``,
e.g. ``"alice@example.com"``.
identifier: The user the token is minted for. Your app's ID for the user,
the same value you use when the user connects. Use a stable internal ID,
not an email address,
the same one used when calling ``ensure_instance``, e.g. ``"user_123"``.
expiry: Requested lifetime for the token as a Python ``timedelta``.
When omitted, the server-side default TTL is applied (typically
1 hour). Example values:
Expand All @@ -1399,7 +1433,7 @@ def create_session_token(

resp = client.actions.mcp.create_session_token(
mcp_config_id="cfg_01abc123",
identifier="alice@example.com",
identifier="user_123",
expiry=timedelta(hours=8),
)

Expand Down
23 changes: 16 additions & 7 deletions scalekit/tools.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,9 +66,10 @@ def list_scoped_tools(
page_token: Optional[str] = None
) -> ListScopedToolsResponse:
"""
Method to list scoped tools for a specific identifier
List the tools a user can call through their connected accounts

:param identifier : Identifier to scope the tools list
:param identifier : Your app's ID for the user, the same value you use
when the user connects. Use a stable internal ID, not an email address
:type : ``` str ```
:param filter : Filter parameters for scoped tools
:type : ``` ScopedToolFilter ```
Expand Down Expand Up @@ -98,7 +99,7 @@ def search_tools(
top_k: Optional[int] = None
) -> SearchToolsResponse:
"""
Method to search tools ranked by relevance to a natural-language query
Search tools ranked by relevance to a natural-language query

Each result's ``score`` is a relevance score where higher is better; it is only
comparable within the results of a single response, not across separate calls.
Expand All @@ -113,8 +114,11 @@ def search_tools(

:param query : Natural-language query or keywords describing the job to be done
:type : ``` str ```
:param identifier : Optional connected-account identifier; when set, each result is
annotated with readiness for this identifier's connections
:param identifier : Optional. Your app's ID for the user, the same value
you use when the user connects. Use a stable internal ID, not an email
address.
When set, each result is annotated with readiness for
this user's connections
:type : ``` str ```
:param top_k : Maximum number of ranked results to return (default 10, capped at 50)
:type : ``` int ```
Expand Down Expand Up @@ -145,15 +149,20 @@ def execute_tool(

:param tool_name : Name of the tool to execute
:type : ``` str ```
:param identifier : Identifier of the connected account
:param identifier : Your app's ID for the user, the same value you use
when the user connects. Use a stable internal ID, not an email address
:type : ``` str ```
:param params : Parameters for tool execution
:type : ``` dict ```
:param connected_account_id : ID of the connected account to use for tool execution
:type : ``` str ```
:param connection_name : Name of the connector/provider (e.g., 'Google Workspace', 'Slack')
:param connection_name : Connection name, as shown in AgentKit > Connections
(for example ``gmail``)
:type : ``` str ```

The connected account must be ``ACTIVE``. Otherwise the call fails with
``INVALID_ARGUMENT``; send the user an authorization link first.

:returns:
Execute Tool Response
"""
Expand Down
Loading