> For the complete documentation index, see [llms.txt](https://ask-clio.gitbook.io/ask-clio/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ask-clio.gitbook.io/ask-clio/tools-and-data-plug-in-your-apis/adding-your-clearing-partner.md). # Adding your Clearing Partner ## Overview Ask Clio allows you to connect your clearing provider so Ask Clio can access data and respond to client questions.
**Alpaca** is currently supported via the flow. We expect to be live with Apex, DriveWealth and RQD. Don't hesitate to reach out to with questions or requests for clearing coverage. ## Connect Your Clearing Firm 1. In the Integrations tab - click “Connect Your Clearing Partner”
2. Choose your clearing partner from the list of options
3. Add you API credentials ***Note: Please use the updated Client Secret API key, not the legacy key. These can be generated in the Alpaca admin center.***
4. Test your tools, and Activate them when you want to set them live!

You can either flag the tools to access your sandbox environment for testing, or connect to production when you’re ready to go live. ## Adding clearing tools from the Clearing Tool List After a clearing integration is connected, firms can add supported clearing tools from the **Clearing Tool List** in the Integrations tab. As Ask Clio releases new tools for supported clearing firms, those tools can be installed from the Clearing Tool List without manually recreating the API configuration. Examples of clearing tools may include: * Account state * Order lookup * Account activity * Portfolio history * Trading actions * Funding actions ### How to add a clearing tool 1. Go to **Integrations**. 2. Click **Clearing Tool List**. 3. Filter by clearing firm if needed. 4. Select the tool you want to add. 5. Click **Add**. 6. Review the tool configuration. 7. Test and activate the tool when ready. Some clearing tools are read-only. Tools that take action, such as trading or funding workflows, may require Secure Client Confirmation before execution. ## Pass Your Client Account Number In order for the model to access your client account information, you need to provide their clearing account number. > **Note on User Identity** > > Clearing account identifiers (such as `alpaca_account_id`) should be passed **only** via Dynamic Inputs. > > Do not use clearing account IDs as `user.id` when creating session tokens.\ > `user.id` should always represent your application’s internal user identifier. > > Chat history is always scoped to `user.id`, not the clearing account. After you add your clearing partner, a clearing ID will populate under the “Dynamic Inputs”

To set up Dynamic Inputs for your client clearing ID: 1. Once you’ve created a clearing integration, the clearing client ID will automatically populate within the Dynamic Inputs tab.
2. Create a Signing Identity: Your client ID will automatically populate, name the signing identity and click create.
You can use this Client Signing Identity for creating tokens on your backend side so users can start a new chat session with Ask Clio.
New clients will have a default signing identity.

## Connect your backend ### Creating a Session Token Once you have a **Client ID** and **API Secret Key**, you can begin securely integrating your backend data with Ask Clio by creating a **session token**. A session token is required to initialize a user session and securely pass runtime context—such as **clearing identifiers** and **Dynamic Inputs**—into Ask Clio tool execution. *** ### Token Creation Endpoint To create a session token, call: ``` POST https://app.askclio.ai/api/auth/v1/client-identities/tokens ``` #### Required Credentials * **`client_id`**\ The Client ID associated with your Ask Clio workspace (found in the Dashboard Configuration tab). * **`client_secret`**\ The API Secret Key created in the previous step. *** ### Request Parameters #### `user` User-specific metadata for the session. * **`id`** (optional but strongly recommended)\ A unique identifier for the user. This value is used to associate and recover previous conversations. * **`email`** (optional)\ The user’s email address. This may be used if the user submits a support request. #### `tools_input` An object containing **clearing identifiers** and/or **Dynamic Inputs**. * The structure of this object depends on your enabled integrations and configured Dynamic Inputs. * Keys must match the Dynamic Inputs defined in the Ask Clio dashboard. * For example, when the Alpaca integration is enabled, `alpaca_account_id` can be passed here to enable Alpaca-specific tools. *** ### Example Token Request > **Note on Identity** > > Clearing account identifiers (such as Alpaca account IDs) are used exclusively for tool execution and must be passed via Dynamic Inputs. > > Clearing identifiers should never be used as `user.id` when creating session tokens. *(with Alpaca integration installed)* ```json { "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "user": { "id": "42", "email": "paul@askclio.ai" }, "tools_input": { "alpaca_account_id": "YOUR_ALPACA_ACCOUNT_ID" } } ``` *** ### Example Response ```json { "token": "...", "expires_at": "2026-01-04T11:36:18.010627Z" } ``` *** ### Using the Session Token (`st`) The returned session token is used to open a new Ask Clio session for the user. The token must be passed either: * Via the SDK, or * Directly in the URL using the `st` query parameter **Session token lifecycle**\ Session tokens (`st`) are short-lived and single-use. A token is generated on your backend, passed to the frontend during session initialization, and **consumed when the Clio session starts**. Tokens cannot be reused or swapped mid-session. If a new user context is required (e.g. after login), a new session must be initialized with a new token. #### Example ``` https://app.askclio.ai/?client_id=&st= ``` #### Security Model * Values carried via the session token are **not exposed to the LLM prompt** * They are only accessible to **tools that explicitly reference them** * The token is scoped to a single session and must be regenerated per session *** ### cURL Example – Create Session Token ```bash curl --request POST \ --url https://app.askclio.ai/api/auth/v1/client-identities/tokens \ --header 'Content-Type: application/json' \ --data '{ "client_id": "", "client_secret": "", "tools_input": { "example": "foobar" }, "user": { "id": "", "email": "" } }' ``` *** ### Revoke Session Token (Not Yet Deployed) ```bash curl --request DELETE \ --url https://app.askclio.ai/api/auth/v1/client-identities/tokens \ --header 'Content-Type: application/json' \ --data '{ "client_id": "", "client_secret": "", "secret_token": "" }' ``` #### Example Response ``` HTTP 204 NO CONTENT ``` *** ### Important Security Note Session tokens **must be generated on your backend**. Do **not** generate or retrieve session tokens on the frontend, as this would expose sensitive credentials and increase the risk of malicious network attacks. **Recommended flow:** 1. Generate the session token on your backend 2. Pass the token to your frontend 3. Initialize Ask Clio using the `st` query parameter or SDK
## Create a Test Session Add a client clearing ID to test the endpoints within the configuration tab.

--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ask-clio.gitbook.io/ask-clio/tools-and-data-plug-in-your-apis/adding-your-clearing-partner.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.