openapi: 3.1.0
info:
  title: Box Oauth2 API
  description: Needs a description.
paths:
  /oauth2/token:
    post:
      operationId: post_oauth2_token
      summary: Box Request access token
      description: |-
        Request an Access Token using either a client-side obtained OAuth 2.0
        authorization code or a server-side JWT assertion.

        An Access Token is a string that enables Box to verify that a
        request belongs to an authorized session. In the normal order of
        operations you will begin by requesting authentication from the
        [authorize](#get-authorize) endpoint and Box will send you an
        authorization code.

        You will then send this code to this endpoint to exchange it for
        an Access Token. The returned Access Token can then be used to to make
        Box API calls.
      tags:
        - Oauth2
      servers:
        - url: https://api.box.com
          description: Server for server-side authentication
      x-box-tag: authorization
      security: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PostOAuth2Token'
      responses:
        '200':
          description: |-
            Returns a new Access Token that can be used to make authenticated
            API calls by passing along the token in a authorization header as
            follows `Authorization: Bearer <Token>`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessToken'
        '400':
          description: An authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
        default:
          description: An authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
  /oauth2/token#refresh:
    post:
      operationId: post_oauth2_token#refresh
      summary: Box Refresh access token
      description: Refresh an Access Token using its client ID, secret, and refresh token.
      tags:
        - Oauth2
      servers:
        - url: https://api.box.com
          description: Server for server-side authentication
      x-box-tag: authorization
      x-box-is-variation: true
      security: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PostOAuth2Token--RefreshAccessToken'
      responses:
        '200':
          description: |-
            Returns a new Access Token that can be used to make authenticated
            API calls by passing along the token in a authorization header as
            follows `Authorization: Bearer <Token>`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessToken'
        '400':
          description: An authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
        default:
          description: An authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
  /oauth2/revoke:
    post:
      operationId: post_oauth2_revoke
      summary: Box Revoke access token
      description: |-
        Revoke an active Access Token, effectively logging a user out
        that has been previously authenticated.
      tags:
        - Oauth2
      servers:
        - url: https://api.box.com
          description: Server for server-side authentication
      x-box-tag: authorization
      security: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PostOAuth2Revoke'
      responses:
        '200':
          description: Returns an empty response when the token was successfully revoked.
        '400':
          description: An authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
        default:
          description: An authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
components:
  schemas:
    AccessToken:
      title: Access token
      type: object
      x-box-resource-id: access_token
      x-box-tag: authorization
      description: A token that can be used to make authenticated API calls.
      properties:
        access_token:
          type: string
          format: token
          example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
          description: The requested access token.
        expires_in:
          type: integer
          format: int64
          example: 3600
          description: The time in seconds by which this token will expire.
        token_type:
          type: string
          enum:
            - bearer
          example: bearer
          description: The type of access token returned.
        restricted_to:
          type: array
          description: |-
            The permissions that this access token permits,
            providing a list of resources (files, folders, etc)
            and the scopes permitted for each of those resources.
          items:
            $ref: '#/components/schemas/FileOrFolderScope'
        refresh_token:
          type: string
          format: token
          example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
          description: |-
            The refresh token for this access token, which can be used
            to request a new access token when the current one expires.
        issued_token_type:
          type: string
          format: urn
          example: urn:ietf:params:oauth:token-type:access_token
          enum:
            - urn:ietf:params:oauth:token-type:access_token
          description: |-
            The type of downscoped access token returned. This is only
            returned if an access token has been downscoped.
    OAuth2Error:
      title: OAuth 2.0 error
      type: object
      x-box-resource-id: oauth2_error
      x-box-tag: authorization
      description: An OAuth 2.0 error
      properties:
        error:
          type: string
          example: invalid_client
          description: The type of the error returned.
        error_description:
          type: string
          example: The client credentials are not valid
          description: The type of the error returned.
tags:
  - name: Oauth2