Skip to main content

OAuth Integration Guide

Webull API uses the OAuth 2.0 protocol for authentication. OAuth 2.0 is a straightforward protocol that third-party platforms can easily integrate with Webull's OAuth 2.0 endpoint.

Authorization and Token Flow Overview​

The three actors in OAuth are:

RoleDefinitionExample
Service providerA service provider that uses OAuth 2.0 to let third-party platforms have limited access to a user's accountWebull
UserAn individual user with an account at the service provider.An individual user with an active account at Webull.
Third-party platformThird-party platform application that accesses the service provider via OAuth 2.0 with the user's authorization.Your application

  1. Register Your Application

    Register your application with Webull. After registration, initiate the authorization process by redirecting the user’s browser to the Webull authorization URL. Once the user completes authorization, parse the returned authorization code and exchange it for an access token, which is used to access Webull APIs.

  2. Provide Application Information

    During registration, provide the following information:

    • Company name
    • Redirect URL (the callback endpoint to which Webull redirects the user after authorization)

  3. Receive Application Credentials

    After successful registration, Webull will issue the following configuration parameters:

    • client_id (Client ID)
    • client_secret (Client Secret)
    • scope (authorization scope)
    • app_key and app_secret (used for request signing)
    Note

    The third-party platform must securely store the client_secret and must not disclose it to any user or third party. If a compromise or potential exposure is detected, please contact us promptly to rotate and replace the credentials.

  4. Obtain an Authorization Code

    Use the Get An Authorization Code API to obtain an authorization code. If the user grants permission to your application, the callback URL registered in your application will be invoked. The interface for obtaining the authorization code is completed in the browser.

    • After the user authorizes access, Webull returns an authorization code.
    • The authorization code is short-lived and expires after 60 seconds.
    • The code can only be used to exchange for an access token.

  5. Create an Access Token

    Use the Create Access Token API to exchange the authorization code for an access token.

    • The access token is required for all subsequent API requests.
    • Access tokens expire every 30 minutes (exact expiration time is returned in the API response).
    • After expiration, a new access token must be obtained.

  6. Refresh the Access Token

    Use the Refresh Access Token API with a valid refresh token.

    • Upon refresh, a new refresh token and access token will be issued.
    • Refresh tokens expire after 15 days (exact expiration time is returned in the API response).

API Calls​

For example, for the Account List API, the UAT environment is:

curl -X GET "https://us-oauth-open-api.uat.Webullbroker.com/oauth-openapi/account/list" \
    -H 'Authorization: Bearer NTJhYjg5MTEtNmI5OS00NDYyLWE5Y2Et' \
    -H 'accept: application/json' \