openapi: 3.1.0
info:
  title: Box Authorize Authorization Device Pinners API
  description: Needs a description.
tags:
- name: Device Pinners
  description: 'Device pinners allow enterprises to

    control what devices can use

    native Box applications.'
  x-box-tag: device_pinners
paths:
  /device_pinners/{device_pinner_id}:
    get:
      operationId: get_device_pinners_id
      summary: Box Get device pin
      tags:
      - Device Pinners
      x-box-tag: device_pinners
      description: Retrieves information about an individual device pin.
      parameters:
      - name: device_pinner_id
        description: The ID of the device pin
        in: path
        required: true
        example: '2324234'
        schema:
          type: string
      responses:
        '200':
          description: Returns information about a single device pin.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DevicePinner'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    delete:
      operationId: delete_device_pinners_id
      summary: Box Remove device pin
      tags:
      - Device Pinners
      x-box-tag: device_pinners
      description: Deletes an individual device pin.
      parameters:
      - name: device_pinner_id
        description: The ID of the device pin
        in: path
        required: true
        example: '2324234'
        schema:
          type: string
      responses:
        '204':
          description: Returns an empty response when the pin has been deleted.
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /enterprises/{enterprise_id}/device_pinners:
    get:
      operationId: get_enterprises_id_device_pinners
      summary: Box List enterprise device pins
      tags:
      - Device Pinners
      x-box-tag: device_pinners
      description: 'Retrieves all the device pins within an enterprise.


        The user must have admin privileges, and the application

        needs the "manage enterprise" scope to make this call.'
      parameters:
      - name: enterprise_id
        description: The ID of the enterprise
        in: path
        required: true
        example: '3442311'
        schema:
          type: string
      - name: marker
        description: 'Defines the position marker at which to begin returning results. This is

          used when paginating using marker-based pagination.


          This requires `usemarker` to be set to `true`.'
        in: query
        required: false
        example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
        schema:
          type: string
      - name: limit
        description: The maximum number of items to return per page.
        in: query
        required: false
        example: 1000
        schema:
          type: integer
          format: int64
          maximum: 1000
      - name: direction
        description: 'The direction to sort results in. This can be either in alphabetical ascending

          (`ASC`) or descending (`DESC`) order.'
        in: query
        required: false
        example: ASC
        schema:
          type: string
          enum:
          - ASC
          - DESC
      responses:
        '200':
          description: Returns a list of device pins for a given enterprise.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DevicePinners'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
components:
  schemas:
    DevicePinner:
      title: Device pinner
      type: object
      x-box-resource-id: device_pinner
      x-box-tag: device_pinners
      description: 'Device pins allow enterprises to control what devices can

        use native Box applications.'
      properties:
        id:
          type: string
          description: The unique identifier for this device pin.
          example: '11446498'
        type:
          type: string
          description: '`device_pinner`'
          example: device_pinner
          enum:
          - device_pinner
        owned_by:
          allOf:
          - $ref: '#/components/schemas/User--Mini'
          - description: The user that the device pin belongs to
        product_name:
          type: string
          description: The type of device being pinned
          example: iPad
    User--Base:
      title: User (Base)
      type: object
      x-box-resource-id: user--base
      x-box-tag: users
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'A mini representation of a user, used when

        nested within another resource.'
      required:
      - type
      - id
      properties:
        id:
          type: string
          description: The unique identifier for this user
          example: '11446498'
        type:
          type: string
          description: '`user`'
          example: user
          nullable: false
          enum:
          - user
    User--Mini:
      title: User (Mini)
      type: object
      x-box-resource-id: user--mini
      x-box-variant: mini
      description: 'A mini representation of a user, as can be returned when nested within other

        resources.'
      allOf:
      - $ref: '#/components/schemas/User--Base'
      - properties:
          name:
            type: string
            description: The display name of this user
            example: Aaron Levie
            maxLength: 50
            nullable: false
          login:
            type: string
            format: email
            description: The primary email address of this user
            example: ceo@example.com
            nullable: false
    ClientError:
      title: Client error
      type: object
      x-box-resource-id: client_error
      description: A generic error
      properties:
        type:
          description: error
          example: error
          type: string
          enum:
          - error
          nullable: false
        status:
          description: The HTTP status of the response.
          example: 400
          type: integer
          format: int32
          nullable: false
        code:
          description: A Box-specific error code
          example: item_name_invalid
          type: string
          enum:
          - created
          - accepted
          - no_content
          - redirect
          - not_modified
          - bad_request
          - unauthorized
          - forbidden
          - not_found
          - method_not_allowed
          - conflict
          - precondition_failed
          - too_many_requests
          - internal_server_error
          - unavailable
          - item_name_invalid
          - insufficient_scope
        message:
          description: A short message describing the error.
          example: Method Not Allowed
          type: string
          nullable: false
        context_info:
          description: 'A free-form object that contains additional context

            about the error. The possible fields are defined on

            a per-endpoint basis. `message` is only one example.'
          type: object
          nullable: true
          properties:
            message:
              type: string
              description: More details on the error.
              example: Something went wrong.
        help_url:
          description: A URL that links to more information about why this error occurred.
          example: https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
          type: string
          nullable: false
        request_id:
          description: 'A unique identifier for this response, which can be used

            when contacting Box support.'
          type: string
          example: abcdef123456
          nullable: false
    DevicePinners:
      title: Device pinners
      type: object
      x-box-resource-id: device_pinners
      x-box-tag: device_pinners
      description: A list of device pins
      properties:
        entries:
          type: array
          description: A list of device pins
          items:
            $ref: '#/components/schemas/DevicePinner'
        limit:
          description: 'The limit that was used for these entries. This will be the same as the

            `limit` query parameter unless that value exceeded the maximum value

            allowed.'
          default: 100
          example: 200
          type: integer
          format: int64
        next_marker:
          description: The marker for the start of the next page of results.
          example: 3000
          type: integer
          format: int64
        order:
          description: The order by which items are returned.
          type: array
          items:
            type: object
            description: The order in which a pagination is ordered
            properties:
              by:
                description: The field that is ordered by
                example: id
                enum:
                - id
                type: string
              direction:
                type: string
                description: The direction to order by, either ascending or descending
                example: asc
                enum:
                - asc
                - desc