openapi: 3.1.0
info:
  title: Battle.net OAuth API
  description: >-
    OAuth 2.0 authorization server for the Battle.net developer platform.
    Supports the authorization code flow (with PKCE) for user-context access
    to Battle.net account and profile scopes, and the client credentials flow
    for accessing public Game Data APIs. Hosted at https://oauth.battle.net.
  version: '1.0'
  contact:
    name: Battle.net Developer Portal
    url: https://develop.battle.net/
servers:
  - url: https://oauth.battle.net
    description: Battle.net OAuth host
tags:
  - name: Authorization
    description: User-context authorization endpoints.
  - name: Token
    description: Token issuance and inspection endpoints.
  - name: UserInfo
    description: OpenID Connect userinfo endpoint.
paths:
  /authorize:
    get:
      operationId: authorize
      summary: Start Authorization Code Flow
      description: Redirects the user to the Battle.net consent screen and returns an authorization code on success.
      tags:
        - Authorization
      parameters:
        - name: client_id
          in: query
          required: true
          schema:
            type: string
        - name: response_type
          in: query
          required: true
          schema:
            type: string
            enum:
              - code
        - name: scope
          in: query
          required: false
          schema:
            type: string
        - name: redirect_uri
          in: query
          required: true
          schema:
            type: string
        - name: state
          in: query
          required: false
          schema:
            type: string
      responses:
        '302':
          description: Redirect to the registered redirect_uri with code and state.
  /token:
    post:
      operationId: createToken
      summary: Create Token
      description: Exchanges an authorization code or client credentials for an access token.
      tags:
        - Token
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum:
                    - authorization_code
                    - client_credentials
                    - refresh_token
                code:
                  type: string
                redirect_uri:
                  type: string
                client_id:
                  type: string
                client_secret:
                  type: string
                refresh_token:
                  type: string
      responses:
        '200':
          description: Token issued.
  /oauth/check_token:
    post:
      operationId: checkToken
      summary: Check Token
      description: Validates an access token and returns information about it.
      tags:
        - Token
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                token:
                  type: string
      responses:
        '200':
          description: Token info returned.
  /oauth/userinfo:
    get:
      operationId: getUserInfo
      summary: Get User Info
      description: Returns the Battle.net account id, battletag, and sub claim for the authenticated user.
      tags:
        - UserInfo
      security:
        - bearerAuth: []
      responses:
        '200':
          description: User info returned.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT