swagger: '2.0'

info:
  version: '1'
  title: Device admission
  description: |
    An API for device admission handling. Intended for use by the web GUI.

basePath: '/api/management/v1/admission'
host: 'docker.mender.io'

schemes:
  - https

paths:
  /devices:
    get:
      summary: List known device data sets
      description: |
        Returns a paged collection of device authentication data sets registered
        for admission, and optionally filters by device admission status.
      parameters:
        - name: Authorization
          in: header
          required: true
          type: string
          format: Bearer [token]
          description: Contains the JWT token issued by the User Administration and Authentication Service.
        - name: status
          in: query
          description: |
            Admission status filter. If not specified, all device data sets are listed.
          required: false
          type: string
          enum:
            - pending
            - accepted
            - rejected
            - preauthorized
        - name: page
          in: query
          description: Starting page.
          required: false
          type: number
          format: integer
          default: 1
        - name: per_page
          in: query
          description: Number of results per page.
          required: false
          type: number
          format: integer
          default: 10
        - name: device_id
          in: query
          description: List auth sets owned by given device
          required: false
          type: string
      responses:
        200:
          description: Successful response.
          schema:
            title: ListOfDevices
            type: array
            items:
              $ref: '#/definitions/Device'
            example:
              application/json:
                - id: "291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e"
                  device_id: "58be8208dd77460001fe0d78"
                  device_identity: "{\"mac\":\"00:01:02:03:04:05\", \"sku\":\"My Device 1\", \"sn\":\"SN1234567890\"}"
                  key: "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzogVU7RGDilbsoUt/DdH\nVJvcepl0A5+xzGQ50cq1VE/Dyyy8Zp0jzRXCnnu9nu395mAFSZGotZVr+sWEpO3c\nyC3VmXdBZmXmQdZqbdD/GuixJOYfqta2ytbIUPRXFN7/I7sgzxnXWBYXYmObYvdP\nokP0mQanY+WKxp7Q16pt1RoqoAd0kmV39g13rFl35muSHbSBoAW3GBF3gO+mF5Ty\n1ddp/XcgLOsmvNNjY+2HOD5F/RX0fs07mWnbD7x+xz7KEKjF+H7ZpkqCwmwCXaf0\niyYyh1852rti3Afw4mDxuVSD7sd9ggvYMc0QHIpQNkD4YWOhNiE1AB0zH57VbUYG\nUwIDAQAB\n-----END PUBLIC KEY-----\n"
                  status: "pending"
                  attributes:
                    mac: "00:01:02:03:04:05"
                    sku: "My Device 1"
                    sn:  "SN1234567890"
                  request_time: "2016-10-03T16:58:51.639Z"
          headers:
            Link:
              type: string
              description: |
                Standard header, used for page navigation.

                Supported relation types are 'first', 'next' and 'prev'.
        400:
          description: |
            Invalid parameters. See error message for details.
          schema:
            $ref: "#/definitions/Error"
        500:
          description: Internal server error.
          schema:
            $ref: "#/definitions/Error"
    post:
      summary: Submit a preauthorized device authentication data set
      description: |
        Adds the device authentication data set to the database with a 'preauthorized'
        admission status. The device identity data set must not yet exist in the DB (regardless of status).

        When the device requests authentication from deviceauth the next time, it will be issued
        a token without further user intervention.
      parameters:
        - name: Authorization
          in: header
          required: true
          type: string
          format: Bearer [token]
          description: Contains the JWT token issued by the User Administration and Authentication Service.
        - name: auth_set
          in: body
          description: The authentication data set to be preauthorized
          required: true
          schema:
            $ref: '#/definitions/AuthSet'
      responses:
        201:
          description: Device authentication data set submitted successfully.
          headers:
            Location:
              type: string
              description: Link to the created auth set.
        400:
          description: |
              The request body is malformed. See error for details.
          schema:
            $ref: "#/definitions/Error"
        409:
          description: Authentication data set (identity data) already exists.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Internal server error.
          schema:
            $ref: "#/definitions/Error"

  /devices/{id}:
    put:
      summary: Submit a device authentication data set for admission
      description: |
        Deprecated endpoint, will be removed in Mender 1.6
        Adds the device authentication data set to the database with a 'pending'
        admission status. If the device already exists, it changes the device's
        status to 'pending' and updates identity data. The user will be able to
        inspect the device, and either accept, or reject it.
      parameters:
        - name: Authorization
          in: header
          required: true
          type: string
          format: Bearer [token]
          description: Contains the JWT token issued by the User Administration and Authentication Service.
        - name: id
          in: path
          description: Device authentication data set identifier.
          required: true
          type: string
        - name: device
          in: body
          description: A device for admission.
          required: true
          schema:
            $ref: '#/definitions/NewDevice'
      responses:
        204:
          description: Device authentication data set submitted successfully.
        400:
          description: |
              The request body is malformed. See error for details.
          schema:
            $ref: "#/definitions/Error"
        500:
          description: Internal server error.
          schema:
            $ref: "#/definitions/Error"
    get:
      summary: Get the details of a selected device authentication data set
      description: Returns the details of a particular device authentication data set.
      parameters:
        - name: Authorization
          in: header
          required: true
          type: string
          format: Bearer [token]
          description: Contains the JWT token issued by the User Administration and Authentication Service.
        - name: id
          in: path
          description: Device authentication data set identifier.
          required: true
          type: string
      responses:
        200:
          description: Successful response - a device authentication data set is returned.
          schema:
            $ref: "#/definitions/Device"
          examples:
            application/json:
              id: "291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e"
              device_id: "58be8208dd77460001fe0d78"
              device_identity: "{\"mac\":\"00:01:02:03:04:05\", \"sku\":\"My Device 1\", \"sn\":\"SN1234567890\"}"
              key: "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzogVU7RGDilbsoUt/DdH\nVJvcepl0A5+xzGQ50cq1VE/Dyyy8Zp0jzRXCnnu9nu395mAFSZGotZVr+sWEpO3c\nyC3VmXdBZmXmQdZqbdD/GuixJOYfqta2ytbIUPRXFN7/I7sgzxnXWBYXYmObYvdP\nokP0mQanY+WKxp7Q16pt1RoqoAd0kmV39g13rFl35muSHbSBoAW3GBF3gO+mF5Ty\n1ddp/XcgLOsmvNNjY+2HOD5F/RX0fs07mWnbD7x+xz7KEKjF+H7ZpkqCwmwCXaf0\niyYyh1852rti3Afw4mDxuVSD7sd9ggvYMc0QHIpQNkD4YWOhNiE1AB0zH57VbUYG\nUwIDAQAB\n-----END PUBLIC KEY-----\n"
              status: "pending"
              attributes:
                mac: "00:01:02:03:04:05"
                sku: "My Device 1"
                sn:  "SN1234567890"
              request_time: "2016-10-03T16:58:51.639Z"
        404:
          description: The device authentication data set was not found.
          schema:
            $ref: "#/definitions/Error"
        500:
          description: Internal server error.
          schema:
            $ref: "#/definitions/Error"
    delete:
      summary: Remove device authentication data set
      description: Removes all device authentication data set data.
      parameters:
        - name: Authorization
          in: header
          required: true
          type: string
          format: Bearer [token]
          description: Contains the JWT token issued by the User Administration and Authentication Service.
        - name: id
          in: path
          description: Device authentication data set identifier
          required: true
          type: string
      responses:
        204:
          description: The device authentication data set was removed.
        500:
          description: Internal server error.
          schema:
           $ref: "#/definitions/Error"
  /devices/{id}/status:
    get:
      summary: Check the admission status of a selected device authentication data set
      description: Returns the admission status of a particular device authentication data set.
      parameters:
        - name: Authorization
          in: header
          required: true
          type: string
          format: Bearer [token]
          description: Contains the JWT token issued by the User Administration and Authentication Service.
        - name: id
          in: path
          description: Device authentication data set identifier.
          required: true
          type: string
      responses:
        200:
          description: |
            Successful response - the device's admission status is returned.
          schema:
            $ref: "#/definitions/Status"
          examples:
            application/json:
              status: "accepted"
        404:
          description: The device authentication data set was not found.
          schema:
            $ref: "#/definitions/Error"
        500:
          description: Internal server error.
          schema:
            $ref: "#/definitions/Error"
    put:
      summary: Update the admission status of a selected device
      description: |
        Changes the given device's admission status.
        Valid state transitions:
        - 'pending' -> 'accepted'
        - 'pending' -> 'rejected'
        - 'rejected' -> 'accepted'
        - 'accepted' -> 'rejected'
      parameters:
        - name: Authorization
          in: header
          required: true
          type: string
          format: Bearer [token]
          description: Contains the JWT token issued by the User Administration and Authentication Service.
        - name: id
          in: path
          description: Device authentication data set identifier.
          required: true
          type: string
        - name: status
          in: body
          description: New status
          required: true
          schema:
            $ref: '#/definitions/Status'
      responses:
        200:
          description: The status of the device authentication data set was successfully updated.
          schema:
            $ref: "#/definitions/Status"
          examples:
            application/json:
              status: "accepted"
        400:
          description: |
              The request body is malformed or the state transition is invalid. See error for details.
          schema:
            $ref: "#/definitions/Error"
        404:
          description: The device authentication data set was not found.
          schema:
            $ref: "#/definitions/Error"
        500:
          description: Internal server error.
          schema:
            $ref: "#/definitions/Error"
definitions:
  Error:
    description: Error descriptor.
    type: object
    properties:
      error:
        description: Description of the error.
        type: string
      request_id:
        description: Request ID (same as in X-MEN-RequestID header).
        type: string
    example:
      application/json:
          error: "failed to decode device group data: JSON payload is empty"
          request_id: "f7881e82-0492-49fb-b459-795654e7188a"
  NewDevice:
    description: New device authentication data set for admission process.
    type: object
    required:
      - device_identity
      - key
      - device_id
    properties:
      device_identity:
        description: The identity data of the device.
        type: string
      key:
        description: Device public key
        type: string
      device_id:
        description: System-assigned device ID.
        type: string
    example:
      application/json:
        id: "291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e"
        device_id: "58be8208dd77460001fe0d78"
        device_identity: "{\"mac\":\"00:01:02:03:04:05\", \"sku\":\"My Device 1\", \"sn\":\"SN1234567890\"}"
        key: "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzogVU7RGDilbsoUt/DdH\nVJvcepl0A5+xzGQ50cq1VE/Dyyy8Zp0jzRXCnnu9nu395mAFSZGotZVr+sWEpO3c\nyC3VmXdBZmXmQdZqbdD/GuixJOYfqta2ytbIUPRXFN7/I7sgzxnXWBYXYmObYvdP\nokP0mQanY+WKxp7Q16pt1RoqoAd0kmV39g13rFl35muSHbSBoAW3GBF3gO+mF5Ty\n1ddp/XcgLOsmvNNjY+2HOD5F/RX0fs07mWnbD7x+xz7KEKjF+H7ZpkqCwmwCXaf0\niyYyh1852rti3Afw4mDxuVSD7sd9ggvYMc0QHIpQNkD4YWOhNiE1AB0zH57VbUYG\nUwIDAQAB\n-----END PUBLIC KEY-----\n"
  AuthSet:
    description: New device authentication data set.
    type: object
    required:
      - device_identity
      - key
    properties:
      device_identity:
        description: The identity data of the device.
        type: string
      key:
        description: Device public key.
        type: string
    example:
      application/json:
        device_identity: "{\"mac\":\"00:01:02:03:04:05\", \"sku\":\"My Device 1\", \"sn\":\"SN1234567890\"}"
        key: "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzogVU7RGDilbsoUt/DdH\nVJvcepl0A5+xzGQ50cq1VE/Dyyy8Zp0jzRXCnnu9nu395mAFSZGotZVr+sWEpO3c\nyC3VmXdBZmXmQdZqbdD/GuixJOYfqta2ytbIUPRXFN7/I7sgzxnXWBYXYmObYvdP\nokP0mQanY+WKxp7Q16pt1RoqoAd0kmV39g13rFl35muSHbSBoAW3GBF3gO+mF5Ty\n1ddp/XcgLOsmvNNjY+2HOD5F/RX0fs07mWnbD7x+xz7KEKjF+H7ZpkqCwmwCXaf0\niyYyh1852rti3Afw4mDxuVSD7sd9ggvYMc0QHIpQNkD4YWOhNiE1AB0zH57VbUYG\nUwIDAQAB\n-----END PUBLIC KEY-----\n"
  Device:
    description: Device authentication data set descriptor.
    type: object
    required:
      - id
      - device_id
      - device_identity
      - key
      - status
      - attributes
      - request_time
    properties:
      id:
        description: Authentication data set identifier.
        type: string
      device_id:
        description: System assigned device identifier.
        type: string
      device_identity:
        description: Identity data
        type: string
      key:
        description: Device public key
        type: string
      status:
        description: Status of the admission process for device authentication data set
        type: string
        enum:
          - pending
          - accepted
          - rejected
          - preauthorized
      attributes:
          $ref: "#/definitions/Attributes"
      request_time:
        type: string
        format: datetime
        description: Server-side timestamp of the request reception.
    example:
      application/json:
        id: "291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e"
        device_id: "58be8208dd77460001fe0d78"
        device_identity: "{\"mac\":\"00:01:02:03:04:05\", \"sku\":\"My Device 1\", \"sn\":\"SN1234567890\"}"
        key: "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzogVU7RGDilbsoUt/DdH\nVJvcepl0A5+xzGQ50cq1VE/Dyyy8Zp0jzRXCnnu9nu395mAFSZGotZVr+sWEpO3c\nyC3VmXdBZmXmQdZqbdD/GuixJOYfqta2ytbIUPRXFN7/I7sgzxnXWBYXYmObYvdP\nokP0mQanY+WKxp7Q16pt1RoqoAd0kmV39g13rFl35muSHbSBoAW3GBF3gO+mF5Ty\n1ddp/XcgLOsmvNNjY+2HOD5F/RX0fs07mWnbD7x+xz7KEKjF+H7ZpkqCwmwCXaf0\niyYyh1852rti3Afw4mDxuVSD7sd9ggvYMc0QHIpQNkD4YWOhNiE1AB0zH57VbUYG\nUwIDAQAB\n-----END PUBLIC KEY-----\n"
        status: "pending"
        attributes:
          mac: "00:01:02:03:04:05"
          sku: "My Device 1"
          sn:  "SN1234567890"
        request_time: "2016-10-03T16:58:51.639Z"

  Status:
    description: Admission status of device authentication data set.
    type: object
    properties:
      status:
        type: string
        enum:
          - pending
          - accepted
          - rejected
    required:
      - status
    example:
      application/json:
          status: "accepted"
  Attributes:
    description: |
      Human readable attributes of the device, in the form of a JSON structure.
      The attributes are completely vendor-specific, the provided ones are just an example.
    type: object
    properties:
      mac:
        description: MAC address.
        type: string
      sku:
        description: Stock keeping unit.
        type: string
      sn:
        description: Serial number.
        type: string
    example:
      application/json:
        mac: "00:01:02:03:04:05"
        sku: "My Device 1"
        sn:  "SN1234567890"