You are browsing documentation for a version other than the latest stable release. Switch to the latest stable release, 1.4.

1.1 APIs Management APIs Device admission

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

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
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
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)