Device admission

Overview

An API for device admission handling. Intended for use by the web GUI.

Version information

Version : 1

URI scheme

Host : docker.mender.io
BasePath : /api/management/v1/admission
Schemes : HTTPS

Paths

List known device data sets

GET /devices

Description

Returns a paged collection of device authentication data sets registered for admission, and optionally filters by device admission status.

Parameters

Type Name Description Schema Default
Header Authorization
required		 Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Query device_id
optional		 List auth sets owned by given device string
Query page
optional		 Starting page. number(integer) "1"
Query per_page
optional		 Number of results per page. number(integer) "10"
Query status
optional		 Admission status filter. If not specified, all device data sets are listed. enum (pending, accepted, rejected)

Responses

HTTP Code Description Schema
200 Successful response.
Headers :
Link (string) : Standard header, used for page navigation.

Supported relation types are 'first', 'next' and 'prev'.		 < Device > array
400 Invalid parameters. See error message for details. Error
500 Internal server error. Error

Example HTTP response

Response 400
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Get the details of a selected device authentication data set

GET /devices/{id}

Description

Returns the details of a particular device authentication data set.

Parameters

Type Name Description Schema Default
Header Authorization
required		 Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path id
required		 Device authentication data set identifier. string

Responses

HTTP Code Description Schema
200 Successful response - a device authentication data set is returned. Device
404 The device authentication data set was not found. Error
500 Internal server error. Error

Example HTTP response

Response 200
json :
{
  "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"
  }
}
Response 404
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Submit a device authentication data set for admission

PUT /devices/{id}

Description

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

Type Name Description Schema Default
Header Authorization
required		 Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path id
required		 Device authentication data set identifier. string
Body device
required		 A device for admission. NewDevice

Responses

HTTP Code Description Schema
204 Device authentication data set submitted successfully. No Content
400 The request body is malformed. See error for details. Error
500 Internal server error. Error

Example HTTP request

Request body
json :
{
  "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"
  }
}

Example HTTP response

Response 400
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Check the admission status of a selected device authentication data set

GET /devices/{id}/status

Description

Returns the admission status of a particular device authentication data set.

Parameters

Type Name Description Schema Default
Header Authorization
required		 Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path id
required		 Device authentication data set identifier. string

Responses

HTTP Code Description Schema
200 Successful response - the device's admission status is returned. Status
404 The device authentication data set was not found. Error
500 Internal server error. Error

Example HTTP response

Response 200
json :
{
  "application/json" : {
    "status" : "accepted"
  }
}
Response 404
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Update the admission status of a selected device

PUT /devices/{id}/status

Description

Changes the given device's admission status. Valid state transitions:

  • 'pending' -> 'accepted'
  • 'pending' -> 'rejected'
  • 'rejected' -> 'accepted'
  • 'accepted' -> 'rejected'

Parameters

Type Name Description Schema Default
Header Authorization
required		 Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path id
required		 Device authentication data set identifier. string
Body status
required		 New status Status

Responses

HTTP Code Description Schema
200 The status of the device authentication data set was successfully updated. Status
400 The request body is malformed or the state transition is invalid. See error for details. Error
404 The device authentication data set was not found. Error
500 Internal server error. Error

Example HTTP request

Request body
json :
{
  "application/json" : {
    "status" : "accepted"
  }
}

Example HTTP response

Response 200
json :
{
  "application/json" : {
    "status" : "accepted"
  }
}
Response 400
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 404
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Definitions

Attributes

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.

Name Description Schema
mac
optional		 MAC address. string
sku
optional		 Stock keeping unit. string
sn
optional		 Serial number. string

Device

Device authentication data set descriptor.

Name Description Schema
attributes
required		 Attributes
device_id
required		 System assigned device identifier. string
device_identity
required		 Identity data string
id
required		 Authentication data set identifier. string
key
required		 Device public key string
request_time
required		 Server-side timestamp of the request reception. string
status
required		 Status of the admission process for device authentication data set enum (pending, accepted, rejected)

Error

Error descriptor.

Name Description Schema
error
optional		 Description of the error. string
request_id
optional		 Request ID (same as in X-MEN-RequestID header). string

NewDevice

New device authentication data set for admission process.

Name Description Schema
device_id
required		 System-assigned device ID. string
device_identity
required		 The identity data of the device. string
key
required		 Device public key string

Status

Admission status of device authentication data set.

Name Description Schema
status
required		 enum (pending, accepted, rejected)