> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitebit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authorize

> The endpoint initiates the OAuth 2.0 authorization flow for user authentication and obtaining an authorization code.

**Using the State Parameter (Best Practice)**

The `state` parameter is crucial for security in OAuth flows:

- Generate a cryptographically secure random string
- Store it in the session before redirecting
- Validate it matches when handling the callback
- This prevents CSRF attacks
<Note>
**Note:** OAuth scopes are predefined during client application setup and cannot be modified during the authorization request. The access token will include all scopes that were approved during client creation.
</Note>


## Used in these guides

* [Fast API Key integration](/guides/fast-api-key-integration) — step 3: build the PKCE authorization URL that sends the end user to the WhiteBIT consent screen.


## OpenAPI

````yaml openapi/oauth2.yaml GET /auth/login
openapi: 3.0.3
info:
  title: OAuth 2.0 API Reference
  description: WhiteBIT OAuth 2.0 API for authentication and account management
  version: 1.0.0
servers:
  - url: https://whitebit.com
    description: WhiteBIT Global Server
  - url: https://whitebit.eu
    description: WhiteBIT EU Server
security: []
tags:
  - name: Authentication
    description: >
      OAuth 2.0 authentication endpoints for obtaining and refreshing access
      tokens.


      Available Scopes (requested during client setup):

      - general: General API access

      - show.userinfo: Access to basic user information

      - users.read: Read user data

      - users.email.read: Read user email information

      - users.kyc.read: Information about whether a user has passed KYC
      verification

      - orders.read: Read trading orders

      - orders.create: Create trading orders

      - orders.delete: Delete trading orders

      - balances.read: Read account balances

      - markets.read: Read market information

      - deals.read: Read trading deals

      - orders_history.read: Read order history

      - users.transactions.read: Read user transactions

      - users.converts.read: Read currency conversion history

      - users.balances.read: Read user account balances

      - users.orders.read: Read user orders

      - users.deals.read: Read user deals

      - apikeys.create: Issue an OAuth-bound API key during the consent flow

      - apikeys.read: Read OAuth-issued API key state and retrieve its secret
      once

      - apikeys.delete: Delete an OAuth-issued API key linked to the partner
  - name: Account Endpoints
    description: >-
      Endpoints for retrieving account information, balances, and transaction
      history
  - name: OAuth API Keys
    description: >
      Partner-facing endpoints for managing API keys created via the OAuth API
      key flow.


      Available on the global server (`https://whitebit.com`) only. The EU
      server (`https://whitebit.eu`) does not expose these endpoints in this
      release.


      Required scopes:

      - `apikeys.read` for `GET /oauth2/api-key/info` and `GET
      /oauth2/api-key/{externalId}/secret`

      - `apikeys.delete` for `DELETE /oauth2/api-key/{externalId}`


      A third scope, `apikeys.create`, authorizes key creation on the WhiteBIT
      consent screen and is not consumed by any endpoint here. Holding at least
      one of the three admits an OAuth2 client to the flow.
paths:
  /auth/login:
    get:
      tags:
        - Authentication
      summary: OAuth 2.0 Authorization
      description: >
        The endpoint initiates the OAuth 2.0 authorization flow for user
        authentication and obtaining an authorization code.


        **Using the State Parameter (Best Practice)**


        The `state` parameter is crucial for security in OAuth flows:


        - Generate a cryptographically secure random string

        - Store it in the session before redirecting

        - Validate it matches when handling the callback

        - This prevents CSRF attacks

        <Note>

        **Note:** OAuth scopes are predefined during client application setup
        and cannot be modified during the authorization request. The access
        token will include all scopes that were approved during client creation.

        </Note>
      parameters:
        - name: clientId
          in: query
          required: true
          description: The application's client ID
          schema:
            type: string
            example: YOUR_CLIENT_ID
        - name: state
          in: query
          required: false
          description: >-
            A secure random string used to maintain state between the request
            and callback and prevent CSRF attacks (Recommended)
          schema:
            type: string
            example: SECURE_RANDOM_STATE
      responses:
        '302':
          description: Redirect to authorization page

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.