Scoped by rep code, not by a shared account.

Access is computed from the claims in your token on every request — the API does not trust a resource id you pass it. On the REST surface, two firms cannot see each other's data, and that isolation runs through one code path rather than a special case per endpoint.

That includes the streams. Server-Sent Events connections and WebSocket subscriptions are authorized with the same predicate as the REST route for the same account, so a stream carries your book and nobody else's. The handshake mechanics are under Events & streaming.

Interpose accepts three credentials. A portal login is a human signing in for an 8-hour token — what a sandbox signup issues, and it works on every pillar. A machine credential is a key pair you issue yourself from that login and your server exchanges for a one-hour token. Request signing is the option where the secret never crosses the wire. Coverage of the latter two is uneven by pillar, and the table below says which is which.

Portal login

curl -X POST https://interposehq.com/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email": "you@yourfirm.com", "password": "..."}'

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type":   "bearer",
  "user": {
    "user_id":  "pauth_01J8Z...",
    "email":    "you@yourfirm.com",
    "role":     "advisor",
    "firm_id":  "firm_01J8Z...",
    "rep_code": "SBX7R01",
    "is_active": true
  }
}

curl -H "Authorization: Bearer $TOKEN" \
  https://interposehq.com/api/v1/pm/portfolios

What the token carries

The payload includes role, firm_id, rep_code and allowed_rep_codes. Authorization is computed from those claims on every request — the API does not trust a resource id you pass it.

A sandbox tenant is an ordinary advisor. That is worth understanding if you are evaluating the security posture rather than the features: sandbox traffic is not a separate authorization branch that could quietly fail open, it rides the same rep-code scoping path every advisor login on the platform exercises daily.

API keys — issue your own

A portal login can mint machine credentials for its own firm, so a signup is all you need to get a server talking to the API. Both BaaS and Portfolio Management issue them, on the same four paths.

curl -X POST https://interposehq.com/api/v1/baas/api-keys/self \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name": "settlement-worker", "permission_group": "read_only"}'

{
  "key_id":            "key_01J8Z...",
  "name":              "settlement-worker",
  "permission_group":  "read_only",
  "allowed_rep_codes": ["SBX7R01"],
  "status":            "active",
  "key_secret":        "ik_live_9f3c..."
}

Portfolio Management issues keys at /api/v1/pm/api-keys/self on the same four paths. Wherever you mint it, one key authenticates on every pillar — brokerage, portfolio management, post-trade, retirement, trust, CRM, agents and network all resolve it from the same store. Issue one, not one per pillar. What it may do on each pillar is decided by its scopes, below.

A key can never be wider than the login that made it

firm_id and allowed_rep_codes are copied from your token. Sending either in the body is a 422 rather than a silent ignore — a caller who believes a scope field was honoured would assume the key is narrower than it is. Only an advisor or branch_supervisor login may issue, so a leaked key cannot be used to manufacture more.

Omitting permission_group gives you read_only. Anything outside the list above returns a 422 naming the valid values; full_access is the operator tier and is not self-grantable. A firm may hold ten active keys at once and the eleventh returns 429, so rotate by issuing the new key before revoking the old one — revocation takes effect immediately. A key belonging to another firm answers 404 on delete, the same as one that does not exist, so this is not a way to probe which key ids are real.

Machine credentials — OAuth 2.0 client credentials

The standard server-to-server flow, RFC 6749 §4.4. Available on BaaS and Portfolio Management.

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_...'

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type":   "Bearer",
  "expires_in":   3600
}

The client_id is the key id (key_…); the client_secret is the secret shown once at issuance (ik_live_…). Swapping them produces a 401 that reads like a credential problem.

HMAC request signing — Portfolio Management only

The high-ceremony option: the secret never crosses the wire. Brokerage-as-a-Service does not accept signed requests on its REST routes — use a bearer token there. Two surfaces are the exception and do take a signed request: the stream-ticket endpoint below, and the Server-Sent Event streams under /v1/events/.

Stream tickets

A WebSocket handshake carries no Authorization header, so the socket takes a single-use ticket you mint over REST with a credential that does — a bearer token or an HMAC-signed request.

{"ticket": "eyJhbGciOiJIUzI1NiIs...", "token_type": "ws_ticket", "expires_in": 60}

The ticket lives 60 seconds, is spent on first use, and carries your entitlement claims frozen at mint time — so the socket authorizes subscriptions against exactly the identity REST would have used. A portal JWT passed in the socket URL is refused, which is the whole point: a token good for eight hours must not become a stream credential because somebody pasted it into a query string. Connecting and subscribing are covered under Events & streaming.

Verifying inbound deliveries

Webhooks invert the direction — there, Interpose authenticates to you and you verify our signature. The scheme and its traps are documented under Events & streaming, alongside the delivery contracts that matter when you design around it: sandbox events dispatch immediately in-process; production events deliver through a durable outbox with retries persisted across restarts.