Adding your Clearing Partner

How to integrate Ask Clio to 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 [e-mail] with questions or requests for clearing coverage.

Connect Your Clearing Firm

1. In the Integrations tab - click “Connect Your Clearing Partner”

1. Choose your clearing partner from the list of options

1. Add you API credentials

1. 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.

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.

1. 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)

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "user": {
    "id": "42",
    "email": "[e-mail]"
  },
  "tools_input": {
    "alpaca_account_id": "YOUR_ALPACA_ACCOUNT_ID"
  }
}

---

Example Response

{
  "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=<YOUR_CLIENT_ID>&st=<SESSION_TOKEN>

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

curl --request POST \
  --url https://app.askclio.ai/api/auth/v1/client-identities/tokens \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "<YOUR_CLIENT_ID>",
    "client_secret": "<YOUR_CLIENT_SECRET>",
    "tools_input": {
      "example": "foobar"
    },
    "user": {
      "id": "<UNIQUE_USER_ID>",
      "email": "<OPTIONAL_EMAIL>"
    }
  }'

---

Revoke Session Token (Not Yet Deployed)

curl --request DELETE \
  --url https://app.askclio.ai/api/auth/v1/client-identities/tokens \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "<YOUR_CLIENT_ID>",
    "client_secret": "<YOUR_CLIENT_SECRET>",
    "secret_token": "<YOUR_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.