openapi: 3.2.0
info:
  description: "The Cellenus APIs require authentication to ensure the request has been authorized to use it. There are two authentication mechanisms supported by Bitvore APIs, an API key and an OAuth access token. See the documentation of each API to see exactly which authentication mechanisms are supported. \n\n An API key not only identifies the caller of an API, it also identifies the scope of the APIs the caller can use. Different API products will issue their own API keys, such as the Corporate and Municipal News APIs respectively. To register for an API key please contact [Bitvore Support](mailto:support@bitvore.com). The API key must then be provided when using the API. The API key can be transmitted to the API in one of three ways, in a query parameter (for GET requests), in an HTTP header, or with an OAuth access token. \n\n To deliver the API key using an query parameter simply include the API key as the value of the HTTP query parameter named \"key\". For example:\n\n ```js\n GET https://api.bitvore.com/v2/corp/news?key=xyz123 HTTP 1.1\n ```\n \n\n To deliver the API key using an HTTP header include the API key as the value of the HTTP header named X-BV-APIKEY. For example: \n\n ```js\n POST https://api.bitvore.com/v2/corp/news \n X-BV-APIKEY: xyz123... \n ```\n \n\n Alternatively an OAuth access token can be used so that the API key is not transmitted with each API call. The OAuth access token is transmitted as a Bearer token in the Authorization HTTP header as described in [RFC6750](https://tools.ietf.org/html/rfc6750). The access token is obtained calling the OAuth API using the client_credentials grant type specifying the registered client id (username) and API key as client secret. \n\n ```js\n POST https://api.bitvore.com/oauth/accesstoken HTTP 1.1\n Content-Type: application/x-www-form-urlencoded \n Accept: application/json \n \n grant_type=client_credentials&client_id=username&client_secret=xyz123 \n ```\n ![Exchange API key for access token](https://bitvorestaticassets.blob.core.windows.net/api-docs/api-key-access-token.png) \n\n Note: No refresh token will be generated by this grant so a new access token must be issued using client credentials when the previous access token expires.\n\n "
  title: Security O Auth2 API
  license:
    name: Copyright Bitvore Corp. 2026
servers:
- url: https://api.bitvore.com/
tags:
- name: OAuth2
  description: Bitvore OAuth2 Authorization Server API
paths:
  /oauth/accesstoken:
    post:
      tags:
      - OAuth2
      summary: Access Token Generation
      description: Issues an access token based on the supplied grant. The server supports both the Resource Owner and Client Credentials grant types, however specific Bitvore API's may only support one. For example only the Client Credentials grant type is supported for the Bitvore News APIs. Please consult the documentation of the API you want to use for its requirements.
      operationId: issueAccessTokenUsingPOST
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessTokenGrantResponse'
                originalRef: AccessTokenGrantResponse
        '400':
          description: Bad requet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
                originalRef: OAuthError
        '500':
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
                originalRef: OAuthError
      deprecated: false
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  default: client_credentials
                  description: Grant type, i.e., client_credentials, password
                username:
                  type: string
                  description: Resource owner's username (use with password grant type)
                password:
                  type: string
                  description: Resource owner's password (use with password grant type)
                client_id:
                  type: string
                  description: Client app ID (use with client_credentials grant type)
                client_secret:
                  type: string
                  description: Resource owner's password (use with client_credentials grant type)
                refreshToken:
                  type: string
                  description: Refresh token
components:
  schemas:
    OAuthError:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
      title: OAuthError
    AccessTokenGrantResponse:
      type: object
      properties:
        access_token:
          type: string
          example: eyJz93aeyJz93a
          description: Base64 encoded access token
        expires_in:
          type: integer
          format: int64
          example: 1800
          description: Time (in seconds) before token expires
        refresh_token:
          type: string
        token_type:
          type: string
          example: Bearer
          description: Type of token returned
      title: AccessTokenGrantResponse