Broker App development involves Client registration, login, authorization, and brokerage-account state. An integration can use either of the following models.
User information stays in the Broker system. Broker persists the relationships among open_id, member_id, the account application, and the brokerage account, and uses its local state to drive Broker App.
flowchart LR
A[Broker user open_id] --> B[Login or register]
B --> C[Whale user member_id]
C --> D[Submit application application_id]
D --> E[Brokerage account account_no]
Link the user
When the Client opens an account for the first time, Broker calls the login and registration endpoint with open_id and receives Whale’s member_id. Reuse the established mapping for that Client.
Submit and store the application
After submitting the account-opening information, Broker stores application_id and changes its local account state to pending.
Synchronize brokerage-account state
Until opening succeeds, Broker periodically queries BrokerAPI. After success, it stores account_no; normal queries can then prefer the result already stored by Broker.
Handle account closure
Broker stores a pending-closure state and continues querying BrokerAPI until closure reaches a final state.
| State | Meaning | Broker App behavior |
|---|---|---|
| Not opened | No application submitted | Show the opening entry point |
| Pending opening | Submitted and processing asynchronously | Show processing and allow a status refresh |
| Opened | A usable brokerage account exists | Store and use account_no |
| Opening failed | The application failed | Show the reason and determine whether retry is allowed |
| Pending closure | Closure started but is not final | Continue querying account state |
Broker Server performs the initial user login or linking and securely hands the returned credentials to Broker App. Broker App sets token and refresh_token in WhaleSDK; a Broker App implementing the securities UI with WhaleCoreSDK sets them in WhaleCoreSDK. The WhaleSDK layer manages the credentials thereafter.
Obtain initial credentials
After login, BrokerAPI returns token and refresh_token. Broker only needs to hand the initial credentials securely to Broker App according to the project design.
Set credentials in the WhaleSDK layer
Broker App sets the initial credentials in WhaleSDK during initialization, or in WhaleCoreSDK when using WhaleCoreSDK. Broker App does not call check token itself.
Let the SDK validate and renew automatically
WhaleSDK or WhaleCoreSDK checks the token lifetime and renews it automatically with the refresh token. As long as renewal continues to succeed, Broker can treat the Client session as long-lived.
Handle the rare unrecoverable failure
If credentials are centrally revoked, the refresh token cannot be used, or another unrecoverable authorization error occurs, the SDK notifies Broker App. Broker App destroys the SDK session, returns the entire App to the logged-out state, and performs the login handoff again.
Broker App must not implement its own token-expiry checks, check-token call, or refresh-token renewal, and must not maintain a second refresh state alongside WhaleSDK or WhaleCoreSDK. Broker Server must still verify ownership and authorization for resources it handles directly.
Next, see User binding and brokerage-account opening for identifiers, states, and endpoint order.