ADR 0008 — Alpaca integration mode: OAuth 2.0 (user-delegated) for v1

Status: Superseded by ADR 0013 and ADR 0014 (2026-04-22) Original date: 2026-04-22 Deciders: product owner (user), software-architect Related: ADR 0002, ADR 0009, ADR 0010, ADR 0011, docs/architecture/multi-tenant-alpaca.md Parent epic: #183

Supersede note (2026-04-22): The premise of this ADR — route every user through Alpaca OAuth for paper + live — has been superseded. Raxx now runs its own paper-trading engine (MBT, per ADR 0013), and Alpaca's role narrows to shared-account market data + optional per-user live-broker handoff (per ADR 0014). The content below is preserved for historical traceability only.

Context

Raxx must connect each tenant's Alpaca brokerage account without holding a long-lived user secret. Three integration shapes are available from Alpaca for a multi-tenant SaaS:

1. Bring-Your-Own-Key (BYOK). User pastes their Alpaca API key + secret into Raxx. Raxx stores it and uses it for all calls.
2. OAuth 2.0 (user-delegated). Raxx registers as an OAuth client with Alpaca; each user authorizes Raxx via Alpaca's consent screen; Raxx receives an access token bounded by scopes. (docs.alpaca.markets/using-oauth2)
3. Broker API. Alpaca becomes Raxx's clearing/custody provider. Raxx holds one Broker API key and manages subaccounts. (docs.alpaca.markets/about-broker-api)

The choice interacts with invariant #1 ("no stored credentials") and with the regulatory posture of the product.

Decision (original — now superseded)

v1 ships with Alpaca OAuth 2.0 (user-delegated).

Concretely:

• Raxx registers an OAuth app with Alpaca (separate registrations for paper and live environments).
• Authorization endpoint: https://app.alpaca.markets/oauth/authorize. Token endpoint: https://api.alpaca.markets/oauth/token.
• Scopes requested are the minimum per feature: data for market-data-only users, trading data for active traders, account:write only when settings-sync is enabled.
• Access tokens (documented as 15-minute validity) are treated as bounded delegation artifacts.

BYOK was explicitly prohibited. Broker API was deferred to the premium tier.

Why superseded

Per ADR 0013, Raxx runs its own paper engine (MBT). Per ADR 0014, Alpaca scope narrows to:

• Market Data API — one shared server-side account (no user OAuth for data).
• Live-broker handoff — per-user Alpaca OAuth only for Pro+ users who explicitly enroll. The OAuth pattern below applies to that narrower subset; see ADR 0014 for the re-scoped version.

The underlying OAuth mechanics described here remain correct — they are just applied to far fewer users now. ADR 0014 is the active decision record for the narrowed surface.

Alternatives considered (historical)

Retained for context — BYOK rejected, Broker API deferred, no-Alpaca rejected, Alpaca Connect API deferred. None of these alternatives change under the reframe; BYOK is still prohibited, and Broker API is now off the roadmap entirely (ADR 0014 §7).

Revisit when

This ADR does not need further revisits. ADR 0014 supersedes it. Future decisions about live-broker OAuth posture amend 0014.