Schwab API

Schwab API is an OAuth 2.0 custodian integration that provides direct access to Charles Schwab advisor accounts. This integration syncs investment accounts, positions, balances, and cost basis data from Schwab’s official Financial Advisor API.

Overview

Attribute	Value
Integration Type	Custodian (API-based)
Authentication	OAuth 2.0 with OpenID Connect
Data Flow	Schwab → RightCapital (inbound only)
Scope	`readonly`
Owner	Yan Hu

Data Synced

Entity	Description
Master Accounts	Financial Advisor master accounts
Accounts	Individual investment accounts under master accounts
Positions	Current holdings with symbol, quantity, price, market value
Balances	Total account balance including cash
Cost Basis	Unrealized gain/loss position data

Authentication

OAuth 2.0 Flow

The integration uses OAuth 2.0 Authorization Code flow with PKCE and HTTP Basic Auth for token exchange.

Token Management

The integration uses ThreadSafeOAuthTokenManager for handling token refresh race conditions:

Token Refresh Before Expiry: Tokens are refreshed 10 seconds before expiration
Redis Locking: Prevents multiple concurrent jobs from refreshing simultaneously
5-Minute Cache: Refreshed tokens cached in Redis for reuse
Transaction Safety: Stashes credentials for recovery if database transaction rolls back

Rate Limits

Endpoint	Rate Limit
Accounts	120 req/min
Positions	120 req/min
Balances	120 req/min
Cost Basis	120 req/min
Transactions	60 req/min

Account Type Mapping

Schwab Type	RightCapital Subtype
`HSA Custodial`, `HSA Master`, `HSBA`	HSA
`403(b)7`, `I401(k)`, `Rtmt Plan Srvc`	401k
`Contrib`, `Rollover`, `Custodial Ira`, `Inh IRA`	Traditional IRA
`Roth Contrib`, `Roth Conversion`	Roth IRA
`Simple Ira`, `Simple Ira Plan`	SIMPLE IRA
`Sep`, `Sarsep`	SEP IRA
`Educ Savings`	529
`Liv Trust`, `Fid Trust`, `Test Trust`	Trust
`Schwab Chartble`	Donor
`Pen Trust`, `PEN ADM`	Pension (Taxable)
(Most others)	Taxable

The full mapping includes 70+ account types.

API Endpoints

Endpoint	Purpose
`master-accounts`	List FA master accounts
`accounts`	List accounts under a master account
`account-owners/list`	Get account details for specific references
`positions/detail`	Get position data for an account
`balances/detail`	Get balance for an account
`cost-basis/ugl-positions`	Get unrealized gain/loss (cost basis)

Code Locations

Component	Path
Connector	`retail-api/app/Integrations/SchwabApi/Connector.php`
Integrator	`retail-api/app/Integrations/SchwabApi/Integrator.php`
Controller	`retail-api/app/Integrations/SchwabApi/Controller.php`
Config	`retail-api/app/Integrations/SchwabApi/Config.php`
Sync	`retail-api/app/Integrations/SchwabApi/Sync.php`
Models	`retail-api/app/Integrations/SchwabApi/Models/`
Token Manager	`retail-api/app/Integrations/Support/LegacyApiBased/Connectors/ThreadSafeOAuthTokenManager.php`

Common Issues

Token Refresh Race Condition

Symptom: Multiple concurrent sync jobs fail with authentication errors.

Solution: The integration uses ThreadSafeOAuthTokenManager with Redis locking.

Terms & Conditions Not Accepted

Symptom: Error about not accepting Schwab Cost Basis Terms & Conditions.

Solution: Advisor must log into Schwab Advisor Center and accept the Cost Basis Terms & Conditions.

Account Not Found (SEC-0100/SEC-0101)

Symptom: Some accounts fail to sync with 401 errors.

Solution: Account was closed, transferred, or authorization was revoked. The advisor may need to reconnect.

Orion - Similar investment account integration