Box Authorization API

openapi: 3.1.0
info:
  title: Box Authorize Authorization API
  description: Needs a description.
tags:
- name: Authorization
  description: 'A set of endpoints used to

    manage user authorization process.'
  x-box-tag: authorization
  x-box-priority: true
paths:
  /authorize:
    get:
      operationId: get_authorize
      summary: Box Authorize user
      description: 'Authorize a user by sending them through the [Box](https://box.com)

        website and request their permission to act on their behalf.


        This is the first step when authenticating a user using

        OAuth 2.0. To request a user''s authorization to use the Box APIs

        on their behalf you will need to send a user to the URL with this

        format.'
      tags:
      - Authorization
      x-box-tag: authorization
      security: []
      servers:
      - url: https://account.box.com/api/oauth2
        description: Server for client-side authentication
      parameters:
      - name: response_type
        description: The type of response we'd like to receive.
        in: query
        example: code
        required: true
        schema:
          type: string
          format: token
          enum:
          - code
      - name: client_id
        description: 'The Client ID of the application that is requesting to authenticate

          the user. To get the Client ID for your application, log in to your

          Box developer console and click the **Edit Application** link for

          the application you''re working with. In the OAuth 2.0 Parameters section

          of the configuration page, find the item labelled `client_id`. The

          text of that item is your application''s Client ID.'
        in: query
        example: ly1nj6n11vionaie65emwzk575hnnmrk
        required: true
        schema:
          type: string
      - name: redirect_uri
        description: 'The URI to which Box redirects the browser after the user has granted

          or denied the application permission. This URI match one of the redirect

          URIs in the configuration of your application. It must be a

          valid HTTPS URI and it needs to be able to handle the redirection to

          complete the next step in the OAuth 2.0 flow.

          Although this parameter is optional, it must be a part of the

          authorization URL if you configured multiple redirect URIs

          for the application in the developer console. A missing parameter causes

          a `redirect_uri_missing` error after the user grants application access.'
        in: query
        example: http://example.com/auth/callback
        required: false
        schema:
          type: string
          format: url
      - name: state
        description: 'A custom string of your choice. Box will pass the same string to

          the redirect URL when authentication is complete. This parameter

          can be used to identify a user on redirect, as well as protect

          against hijacked sessions and other exploits.'
        in: query
        example: my_state
        required: false
        schema:
          type: string
      - name: scope
        description: 'A space-separated list of application scopes you''d like to

          authenticate the user for. This defaults to all the scopes configured

          for the application in its configuration page.'
        in: query
        example: admin_readwrite
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Does not return any data, but rather should be used in the browser.
          content:
            text/html:
              schema:
                type: string
                format: html
        default:
          description: Does not return any data, but rather should be used in the browser.
          content:
            text/html:
              schema:
                type: string
                format: html
  /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:
      - Authorization
      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:
      - Authorization
      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:
      - Authorization
      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.'
    PostOAuth2Token:
      title: Token request
      type: object
      description: A request for a new OAuth 2.0 token
      required:
      - grant_type
      properties:
        grant_type:
          type: string
          format: urn
          example: authorization_code
          description: 'The type of request being made, either using a client-side obtained

            authorization code, a refresh token, a JWT assertion, client credentials

            grant or another access token for the purpose of downscoping a token.'
          enum:
          - authorization_code
          - refresh_token
          - client_credentials
          - urn:ietf:params:oauth:grant-type:jwt-bearer
          - urn:ietf:params:oauth:grant-type:token-exchange
        client_id:
          type: string
          description: 'The Client ID of the application requesting an access token.


            Used in combination with `authorization_code`, `client_credentials`, or

            `urn:ietf:params:oauth:grant-type:jwt-bearer` as the `grant_type`.'
          example: ly1nj6n11vionaie65emwzk575hnnmrk
        client_secret:
          type: string
          description: 'The client secret of the application requesting an access token.


            Used in combination with `authorization_code`, `client_credentials`, or

            `urn:ietf:params:oauth:grant-type:jwt-bearer` as the `grant_type`.'
          example: hOzsTeFlT6ko0dme22uGbQal04SBPYc1
        code:
          type: string
          format: token
          description: 'The client-side authorization code passed to your application by

            Box in the browser redirect after the user has successfully

            granted your application permission to make API calls on their

            behalf.


            Used in combination with `authorization_code` as the `grant_type`.'
          example: n22JPxrh18m4Y0wIZPIqYZK7VRrsMTWW
        refresh_token:
          type: string
          format: token
          description: 'A refresh token used to get a new access token with.


            Used in combination with `refresh_token` as the `grant_type`.'
          example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
        assertion:
          type: string
          format: jwt
          description: 'A JWT assertion for which to request a new access token.


            Used in combination with `urn:ietf:params:oauth:grant-type:jwt-bearer`

            as the `grant_type`.'
          example: xxxxx.yyyyy.zzzzz
        subject_token:
          type: string
          format: token
          description: 'The token to exchange for a downscoped token. This can be a regular

            access token, a JWT assertion, or an app token.


            Used in combination with `urn:ietf:params:oauth:grant-type:token-exchange`

            as the `grant_type`.'
          example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
        subject_token_type:
          type: string
          example: urn:ietf:params:oauth:token-type:access_token
          description: 'The type of `subject_token` passed in.


            Used in combination with `urn:ietf:params:oauth:grant-type:token-exchange`

            as the `grant_type`.'
          enum:
          - urn:ietf:params:oauth:token-type:access_token
        actor_token:
          type: string
          format: token
          description: 'The token used to create an annotator token.

            This is a JWT assertion.


            Used in combination with `urn:ietf:params:oauth:grant-type:token-exchange`

            as the `grant_type`.'
          example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
        actor_token_type:
          type: string
          format: urn
          example: urn:ietf:params:oauth:token-type:id_token
          description: 'The type of `actor_token` passed in.


            Used in combination with `urn:ietf:params:oauth:grant-type:token-exchange`

            as the `grant_type`.'
          enum:
          - urn:ietf:params:oauth:token-type:id_token
        scope:
          type: string
          format: space_delimited_list
          description: 'The space-delimited list of scopes that you want apply to the

            new access token.


            The `subject_token` will need to have all of these scopes or

            the call will error with **401 Unauthorized**.'
          example: item_upload item_preview base_explorer
        resource:
          type: string
          format: url
          description: Full URL for the file that the token should be generated for.
          example: https://api.box.com/2.0/files/123456
        box_subject_type:
          type: string
          example: enterprise
          description: Used in combination with `client_credentials` as the `grant_type`.
          enum:
          - enterprise
          - user
        box_subject_id:
          type: string
          example: '123456789'
          description: 'Used in combination with `client_credentials` as the `grant_type`.

            Value is determined by `box_subject_type`. If `user` use user ID and if

            `enterprise` use enterprise ID.'
        box_shared_link:
          type: string
          format: url
          description: 'Full URL of the shared link on the file or folder

            that the token should be generated for.'
          example: https://cloud.box.com/s/123456
    FileVersion--Base:
      title: File version (Base)
      type: object
      x-box-resource-id: file_version--base
      x-box-sanitized: true
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'The bare basic representation of a file version, the minimal

        amount of fields returned when using the `fields` query

        parameter.'
      required:
      - id
      - type
      properties:
        id:
          type: string
          nullable: false
          description: The unique identifier that represent a file version.
          example: '12345'
        type:
          type: string
          description: '`file_version`'
          example: file_version
          enum:
          - file_version
          nullable: false
    Folder--Base:
      title: Folder (Base)
      type: object
      x-box-resource-id: folder--base
      x-box-sanitized: true
      x-box-tag: folders
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'The bare basic representation of a folder, the minimal

        amount of fields returned when using the `fields` query

        parameter.'
      required:
      - id
      - type
      properties:
        id:
          type: string
          nullable: false
          description: 'The unique identifier that represent a folder.


            The ID for any folder can be determined

            by visiting a folder in the web application

            and copying the ID from the URL. For example,

            for the URL `https://*.app.box.com/folders/123`

            the `folder_id` is `123`.'
          example: '12345'
        etag:
          type: string
          nullable: true
          example: '1'
          description: 'The HTTP `etag` of this folder. This can be used within some API

            endpoints in the `If-Match` and `If-None-Match` headers to only

            perform changes on the folder if (no) changes have happened.'
        type:
          type: string
          description: '`folder`'
          example: folder
          enum:
          - folder
          nullable: false
    Folder--Mini:
      title: Folder (Mini)
      type: object
      x-box-resource-id: folder--mini
      x-box-variant: mini
      description: 'A mini representation of a file version, used when

        nested under another resource.'
      allOf:
      - $ref: '#/components/schemas/Folder--Base'
      - properties:
          sequence_id:
            allOf:
            - type: string
              example: '3'
              nullable: true
              description: 'A numeric identifier that represents the most recent user event

                that has been applied to this item.


                This can be used in combination with the `GET /events`-endpoint

                to filter out user events that would have occurred before this

                identifier was read.


                An example would be where a Box Drive-like application

                would fetch an item via the API, and then listen to incoming

                user events for changes to the item. The application would

                ignore any user events where the `sequence_id` in the event

                is smaller than or equal to the `sequence_id` in the originally

                fetched resource.'
            - nullable: false
          name:
            type: string
            description: The name of the folder.
            example: Contracts
            nullable: false
    File--Base:
      title: File (Base)
      type: object
      x-box-resource-id: file--base
      x-box-sanitized: true
      x-box-tag: files
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      nullable: true
      description: 'The bare basic representation of a file, the minimal

        amount of fields returned when using the `fields` query

        parameter.'
      required:
      - id
      - type
      properties:
        id:
          type: string
          nullable: false
          description: 'The unique identifier that represent a file.


            The ID for any file can be determined

            by visiting a file in the web application

            and copying the ID from the URL. For example,

            for the URL `https://*.app.box.com/files/123`

            the `file_id` is `123`.'
          example: '12345'
        etag:
          type: string
          example: '1'
          nullable: true
          description: 'The HTTP `etag` of this file. This can be used within some API

            endpoints in the `If-Match` and `If-None-Match` headers to only

            perform changes on the file if (no) changes have happened.'
        type:
          type: string
          description: '`file`'
          example: file
          enum:
          - file
          nullable: false
    FileOrFolderScope:
      title: File or folder scope
      type: object
      description: A relation between a resource (file or folder) and the scopes for which the resource can be accessed
      properties:
        scope:
          type: string
          description: The scopes for the resource access
          example: item_download
          enum:
          - annotation_edit
          - annotation_view_all
          - annotation_view_self
          - base_explorer
          - base_picker
          - base_preview
          - base_upload
          - item_delete
          - item_download
          - item_preview
          - item_rename
          - item_share
        object:
          allOf:
          - oneOf:
            - $ref: '#/components/schemas/Folder--Mini'
            - $ref: '#/components/schemas/File--Mini'
          - description: The file or folder resource
    FileVersion--Mini:
      title: File version (Mini)
      type: object
      x-box-resource-id: file_version--mini
      x-box-variant: mini
      description: 'A mini representation of a file version, used when

        nested within another resource.'
      allOf:
      - $ref: '#/components/schemas/FileVersion--Base'
      - properties:
          sha1:
            type: string
            description: The SHA1 hash of this version of the file.
            example: 134b65991ed521fcfe4724b7d814ab8ded5185dc
    PostOAuth2Revoke:
      title: Token revocation request
      type: object
      description: A request to revoke an OAuth 2.0 token
      required:
      - grant_type
      properties:
        client_id:
          type: string
          description: 'The Client ID of the application requesting to revoke the

            access token.'
          example: ly1nj6n11vionaie65emwzk575hnnmrk
        client_secret:
          type: string
          description: 'The client secret of the application requesting to revoke

            an access token.'
          example: hOzsTeFlT6ko0dme22uGbQal04SBPYc1
        token:
          type: string
          format: token
          description: The access token to revoke.
          example: n22JPxrh18m4Y0wIZPIqYZK7VRrsMTWW
    File--Mini:
      title: File (Mini)
      type: object
      x-box-resource-id: file--mini
      x-box-variant: mini
      description: 'A mini representation of a file, used when

        nested under another resource.'
      nullable: true
      allOf:
      - $ref: '#/components/schemas/File--Base'
      - properties:
          sequence_id:
            allOf:
            - type: string
              example: '3'
              nullable: true
              description: 'A numeric identifier that represents the most recent user event

                that has been applied to this item.


                This can be used in combination with the `GET /events`-endpoint

                to filter out user events that would have occurred before this

                identifier was read.


                An example would be where a Box Drive-like application

                would fetch an item via the API, and then listen to incoming

                user events for changes to the item. The application would

                ignore any user events where the `sequence_id` in the event

                is smaller than or equal to the `sequence_id` in the originally

                fetched resource.'
            - nullable: false
          name:
            type: string
            description: The name of the file
            example: Contract.pdf
          sha1:
            type: string
            format: digest
            nullable: false
            example: 85136C79CBF9FE36BB9D05D0639C70C265C18D37
            description: 'The SHA1 hash of the file. This can be used to compare the contents

              of a file on Box with a local file.'
          file_version:
            allOf:
            - $ref: '#/components/schemas/FileVersion--Mini'
            - description: The information about the current version of the file.
    PostOAuth2Token--RefreshAccessToken:
      title: Refresh access token
      type: object
      description: 'A request to refresh an Access Token. Use this API to refresh an expired

        Access Token using a valid Refresh Token.'
      required:
      - grant_type
      - client_id
      - client_secret
      - refresh_token
      properties:
        grant_type:
          type: string
          format: urn
          example: refresh_token
          description: The type of request being made, in this case a refresh request.
          enum:
          - refresh_token
        client_id:
          type: string
          description: The client ID of the application requesting to refresh the token.
          example: ly1nj6n11vionaie65emwzk575hnnmrk
        client_secret:
          type: string
          description: The client secret of the application requesting to refresh the token.
          example: hOzsTeFlT6ko0dme22uGbQal04SBPYc1
        refresh_token:
          type: string
          format: token
          description: The refresh token to refresh.
          example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
    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.