Account Discovery & Auth

Relevant source files

The following files were used as context for generating this wiki page:

• examples/auth_management.py
• stackone_ai/tools.py
• stackone_ai/types.py
• CLAUDE.md
• README.md
• tests/test_fetch_tools.py

Account Discovery and Authentication in the StackOne AI SDK manage how the library identifies and authorizes access to linked SaaS accounts. The SDK requires a StackOne API key to authenticate requests and provides automated discovery of active accounts to reduce manual configuration.

The StackOneToolSet class serves as the primary interface for these operations. It manages the lifecycle of authentication tokens and account identifiers across tool discovery, searching, and execution.

Authentication Mechanisms

The SDK uses Basic Authentication to communicate with the StackOne API. You must provide a STACKONE_API_KEY, which the SDK formats into a standard Authorization header by base64 encoding the key followed by a colon.

API Key Configuration

You can provide the API key in two ways:

1. Environment Variable: The SDK automatically reads the STACKONE_API_KEY variable from the environment.
2. Explicit Initialization: You pass the api_key string directly to the StackOneToolSet constructor.

Sources: examples/auth_management.py:23-33, stackone_ai/tools.py:101-103

Header Construction

Every request sent to the StackOne API includes specific headers for identification and security.

Header Name	Value Source	Description
Authorization	build_auth_header(api_key)	Base64 encoded Basic Auth token.
User-Agent	stackone-ai-python/<version>	SDK identifier for server-side logging.
x-account-id	Tool._account_id	The specific linked account ID for the request scope.

Sources: stackone_ai/tools.py:101-103, stackone_ai/tools.py:382-390, stackone_ai/tools.py:791-797

Account Discovery Process

Account discovery is the process of identifying which SaaS accounts are linked to a specific API key. If you do not provide specific account IDs, the SDK calls the /accounts endpoint to find all accounts with an active status.

Discovery Logic

When discovery triggers:

1. The SDK sends a GET request to /accounts.
2. It filters the results to include only accounts where status == "active".
3. It uses these discovered IDs for all subsequent tool fetching and execution within that ToolSet instance.

Sources: CLAUDE.md:24-27, README.md:65-67, tests/test_fetch_tools.py:465-475

Discovery Flow

The following diagram illustrates how the SDK resolves account IDs when a user requests tools without providing specific identifiers.

Account Scoping and Overrides

The SDK provides multiple layers for scoping operations to specific accounts, allowing for global settings or granular per-tool overrides.

Scoping Levels

1. Global ToolSet Scope: Use toolset.set_accounts(["acc-123"]) to bind all subsequent calls from that toolset instance to specific accounts.
2. Call-specific Scope: Pass account_ids to fetch_tools() to override global settings for a single tool fetching operation.
3. Tools Collection Scope: Use tools.set_account_id("acc-456") on a Tools collection to update the scope for all tools in that collection.
4. Individual Tool Scope: Use tool.set_account_id("acc-789") to target a single action to a specific account.

Sources: examples/auth_management.py:48-77, tests/test_fetch_tools.py:87-101

Scoped Execution Sequence

When executing a tool, the SDK ensures the specific account context is preserved to prevent cross-account data leakage.

Error Handling

Authentication and discovery errors are categorized within the StackOneError hierarchy to allow precise exception handling.

Exception Class	Trigger Condition
StackOneAPIError	The API returns 401 (Unauthorized) or 400 (Missing x-account-id).
ToolsetLoadError	All accounts fail to return tools during discovery.
StackOneError	General network failures or request timeouts.

Sources: stackone_ai/types.py:46-77, tests/test_fetch_tools.py:438-445, stackone_ai/tools.py:165-185

Summary

Account Discovery and Authentication ensure that every tool interaction is correctly authorized and scoped to the intended SaaS instance. By combining automatic discovery of active accounts with explicit scoping methods, the SDK balances ease of use for general agents with strict multi-tenant requirements for production environments. All execution paths strictly enforce account headers to prevent unscoped requests that would otherwise be rejected by the StackOne API.