Build on the engines, not around them.

Interpose Invest is a front end over a Portfolio Management and brokerage platform that is API-first underneath. Everything the advisor portal and the client app do, they do by calling these APIs — so anything you see in the product, you can drive yourself, embed in your own application, or white-label as your own.

This section covers the two pillars that matter for a wealth or investing integration: Portfolio Management — portfolios, models, drift, rebalancing, performance, tax lots, billing — and Brokerage-as-a-Service — accounts, orders, positions, transactions and market data. Authentication sits alongside both.

What is live today

The markers below mean exactly one thing each, here and on every page in this section. Live exists and has test coverage today. Target is something we are building toward and have not measured. By arrangement works, but needs a conversation with us to set up. Registration only means the configuration half exists and the delivery half does not. Not available is not reachable from your infrastructure today, whatever the specifications say.

Where a capability is not reachable from your infrastructure, you will find it under Current limits on the page it belongs to, rather than discovering it in an afternoon.

Base URLs

There is one environment, and it is a simulated evaluation environment. Interpose operates no production environment and will not before FINRA approval.

https://interposehq.com/api/v1/{pillar}/{resource}

GET https://interposehq.com/api/v1/baas/accounts
GET https://interposehq.com/api/v1/pm/portfolios

https://interposehq.com/api/{pillar}

BaasClient(base_url="https://interposehq.com/api/baas")

Authentication

Three credentials, and all of them resolve to the same thing: the firm and rep codes the credential belongs to. Authorization is computed from those claims on every request — the API does not trust a resource id you pass it. Full detail, including which pillar accepts which, is on the authentication page.

Machine credentials are self-serve

Mint a key with the portal login your signup issued. The key is always scoped to the firm and rep codes of the login that created it — supplying firm_id or allowed_rep_codes in the body is a 422, not a silent ignore, so a key can never be broadened past the person who asked for it. Ten active keys per firm; full_access stays an operator-issued group.

# Self-grantable groups — BaaS: read_only · trading · account_management
#                        PM:   read_only · portfolio_management · advisory
curl -X POST https://interposehq.com/api/v1/baas/api-keys/self \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name": "reporting-job", "permission_group": "read_only"}'

# -> {"key_id": "key_01J8Z...", "key_secret": "ik_live_..."}   secret shown once

# The token endpoint is form-encoded, per RFC 6749 — data=, not json=
curl -X POST https://interposehq.com/api/v1/baas/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=key_01J8Z...' \
  -d 'client_secret=ik_live_...'

Request signing

Three headers on every request, with the timestamp in unix milliseconds. Requests more than 30 seconds old are rejected, so sign at send time rather than caching a signature.

X-VM-Key-Id:    key_01J8Z...
X-VM-Timestamp: 1715441400000          # unix MILLISECONDS
X-VM-Signature: hex(HMAC-SHA256(secret, canonical_string))

{METHOD}\n{PATH}\n{TIMESTAMP_MS}\n{SHA256_HEX(body)}

PATH is the service-side path — /v1/portfolios, not the public /api/v1/pm/portfolios. The proxy strips the pillar segment before the service sees it, so signing the public path produces a signature over a string the verifier never reconstructs.

Event streams

Every state change emits a CloudEvents 1.0 envelope on Kafka. Three transports carry it to you: Server-Sent Events, WebSocket, and direct Kafka consumption by arrangement. Two of them carry that envelope verbatim; the WebSocket sends its own lighter frame shape instead, which matters if you were planning to dedupe on the envelope id. Both HTTP transports are firm-scoped — naming an account you are not entitled to is a 403. The full treatment, including the frame shapes and the webhook signature scheme, is on Events & streaming.

{
  "specversion":     "1.0",
  "id":              "evt_01HV4Y2K3M5N8P9QR2ST4UVWXY",
  "source":          "com.interpose.baas",
  "type":            "com.interpose.baas.order.filled",
  "datacontenttype": "application/json",
  "time":            "2026-05-11T14:23:00.000000000Z",
  "issandbox":       true,
  "data":            { }
}

On SSE and Kafka, dedupe on id: delivery is at-least-once and a reconnect can replay. WebSocket frames carry no envelope id, so if you need deduplication that is a reason to choose SSE. SSE is the simpler transport in general — an ordinary GET with a bearer token, no handshake, and it passes through the corporate proxies that block WebSockets. WebSocket costs one extra round trip for the ticket and gives you a duplex connection you can subscribe and re-subscribe on.

The WebSocket handshake

Ask for a ticket over normal HTTP, then connect with it. Tickets are single-use and live 60 seconds. The reason for a ticket rather than ?token= is narrow and worth stating: the server logs handshake query strings, and a portal token lives eight hours, so a logged token is a session handover. A 60-second single-use ticket in a log is spent.

POST /api/v1/baas/stream/tickets       # bearer token or a signed request
# -> {"ticket": "...", "token_type": "ws_ticket", "expires_in": 60}

wss://interposehq.com/api/v1/baas/stream?ticket=<ticket>
wss://interposehq.com/api/v1/pm/pm/stream?ticket=<ticket>

# then, on the open socket
-> {"action": "subscribe", "account_id": "acct_01HV4Y..."}
<- {"type": "subscribed",  "account_id": "acct_01HV4Y..."}

If you would rather not make two calls, offer the subprotocols interpose.v1 and interpose.token.<ticket> on the upgrade instead. A rejected handshake is an HTTP 403 with no close frame and no close code — the connection never got far enough to have one, so do not write a handler that waits for a code. Close codes exist only after a successful accept: 4403 is a subscription to something your credential cannot see, 4002 a malformed or missing subscribe frame.

Kafka topics

Direct consumption is arranged during onboarding rather than self-serve. The topic prefix is vm. for historical reasons while the CloudEvents type field uses com.interpose.* — two namespaces, both correct.

Errors

Every error returns JSON with a detail field. It has three shapes — a string, a validation list, or a compliance object carrying failed_checks — and 422 is used for both schema failures and business-rule rejections, so branch on the shape rather than on the status. The three shapes are set out on API conventions.

IDs, types and precision

Entity ids are ULIDs with a type prefix — lexicographically sortable, so sorting by id sorts by creation time, and safe to put in a URL.

Money and quantities are strings, never JSON numbers. Parse them into a decimal type — Decimal, BigDecimal, whatever your language calls it — and not into a float. A cent lost to binary floating point is a reportable break, not a rounding curiosity.

Every monetary amount carries an explicit currency field, and returns are decimal fractions rather than percentages — "0.0452318920" is 4.52%, not 0.045%. Security identifiers are typed objects rather than bare strings. Both, and the pagination shapes, are on API conventions.

On specification coverage

The published OpenAPI specifications are hand-maintained and describe roughly 180 operations. Portfolio Management and BaaS alone expose around 800. Where a specification is silent, the endpoint may still exist — ask us rather than assuming it does not. The endpoint reference here lists only routes that have been confirmed against the running services.

The things your CTO will not ask about

This section is written for whoever is doing the integration, but the questions that decide whether it happens are usually somebody else's. Short answers, so nobody has to email us to get them.

Where to go next

For the full four-pillar platform — Post-Trade and Retirement Plan Administration alongside these two — platform.interposehq.com/docs carries the complete reference.