You are browsing documentation for a version other than the latest stable release. Switch to the latest stable release, 1.4.
An API for device admission handling. Intended for use by the web GUI.
Version : 1
Host : docker.mender.io
BasePath : /api/management/v1/admission
Schemes : HTTPS
GET /devices
Returns a paged collection of device authentication data sets registered for admission, and optionally filters by device admission status.
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) |
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 |
json :
{
"application/json" : {
"error" : "failed to decode device group data: JSON payload is empty",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"error" : "failed to decode device group data: JSON payload is empty",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
GET /devices/{id}
Returns the details of a particular device authentication data set.
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 |
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 |
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"
}
}
json :
{
"application/json" : {
"error" : "failed to decode device group data: JSON payload is empty",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"error" : "failed to decode device group data: JSON payload is empty",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
PUT /devices/{id}
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.
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 |
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 |
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"
}
}
json :
{
"application/json" : {
"error" : "failed to decode device group data: JSON payload is empty",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"error" : "failed to decode device group data: JSON payload is empty",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
GET /devices/{id}/status
Returns the admission status of a particular device authentication data set.
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 |
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 |
json :
{
"application/json" : {
"status" : "accepted"
}
}
json :
{
"application/json" : {
"error" : "failed to decode device group data: JSON payload is empty",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"error" : "failed to decode device group data: JSON payload is empty",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
PUT /devices/{id}/status
Changes the given device's admission status. Valid state transitions:
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 |
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 |
json :
{
"application/json" : {
"status" : "accepted"
}
}
json :
{
"application/json" : {
"status" : "accepted"
}
}
json :
{
"application/json" : {
"error" : "failed to decode device group data: JSON payload is empty",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"error" : "failed to decode device group data: JSON payload is empty",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"error" : "failed to decode device group data: JSON payload is empty",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
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 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 descriptor.
Name | Description | Schema |
---|---|---|
error optional |
Description of the error. | string |
request_id optional |
Request ID (same as in X-MEN-RequestID header). | string |
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 |
Admission status of device authentication data set.
Name | Description | Schema |
---|---|---|
status required |
enum (pending, accepted, rejected) |