import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Authentication Overview


Webull OpenAPI uses a signature-based authentication mechanism to ensure the security of every API call. This page explains the authentication model and how the components work together.

## How It Works

Every API request to Webull must include two things:

1. **Signature** — A cryptographic signature (e.g. HMAC-SHA1) computed from the request content and your App Secret. This proves the request is authentic and hasn't been tampered with.
2. **Token (Optional)** — If Two-Factor Authentication (2FA) is enabled, a reusable access token verified via the Webull App is also required.
    
    - [Enable/Disable 2FA on the official website](individual-application.md#step-2-register-your-application)

All API requests must be made over HTTPS. Calls made over HTTP will fail. Unauthenticated requests will also fail.

## Authentication Flow

| Step | Action | Details |
|------|--------|---------|
| 1 | Obtain API credentials | Apply for API access and generate your App Key and App Secret |
| 2 | Sign each request | Compute a cryptographic signature from the request content using your App Secret. The SDK handles this automatically. |
| 3 | Create a Token (if 2FA enabled) | The SDK initiates Token creation automatically; you only need to complete verification in the Webull App |
| 4 | Include credentials in headers | Add `x-app-key`, `x-signature`, and optionally `x-access-token` to every request |

## Required Request Headers

| Header | Required | Description |
|--------|----------|-------------|
| `x-app-key` | Yes | A unique identifier issued to a developer for accessing the API |
| `x-timestamp` | Yes | Request timestamp in ISO 8601 format: `YYYY-MM-DDThh:mm:ssZ` (UTC only) |
| `x-signature` | Yes | Cryptographic signature verifying the authenticity and integrity of the request |
| `x-signature-algorithm` | Yes | Signature algorithm (e.g. `HMAC-SHA1`) |
| `x-signature-version` | Yes | Signature algorithm version (e.g. `1.0`) |
| `x-signature-nonce` | Yes | Unique random string, regenerated for each request |
| `x-version` | Yes | Interface version (accepts `v2`) |

:::info About App Secret
The `app_secret` is used solely on the client side for [signature generation](signature.md). It is **not** included as an HTTP request header.
:::

:::tip SDK Users
The Webull SDK handles both signature generation and Token creation/verification automatically. You only need to configure your App Key and App Secret — the SDK takes care of the rest, including the 2FA flow.
:::

## Managing Your Credentials

You can view and manage your App Key and App Secret on the [Webull Official Website](https://www.webull.co.jp) under **OpenAPI Management > App Management**.

:::danger Security Warning
Your App Key and App Secret contain important access permissions. **Never** expose them in public places such as GitHub repositories, client-side code, or forums.
:::

## Next Steps

- [Individual Application Process](individual-application.md) — Step-by-step guide for individual traders to apply for API access and generate credentials
- [Signature](signature.md) — Detailed signature generation algorithm and examples
- [Token](token.md) — Token creation, verification, and lifecycle management