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 devices

GET /devices

Description

Returns a paged collection of devices 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 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 devices 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

GET /devices/{id}

Description

Returns the details of a particular device.

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 identifier (SHA256 over identity data). string

Responses

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

Example HTTP response

Response 200
json :
{
  "application/json" : {
    "id" : "291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e",
    "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 for admission

PUT /devices/{id}

Description

Adds the device 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 identifier (SHA256 over identity data). string
Body device
required
A device for admission. NewDevice

Responses

HTTP Code Description Schema
204 The device for admission 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_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

GET /devices/{id}/status

Description

Returns the admission status of a particular device.

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 identifier (SHA256 over identity data). string

Responses

HTTP Code Description Schema
200 Successful response - the device's admission status is returned. Status
404 The device 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 identifier (SHA256 over identity data). string
Body status
required
New status Status

Responses

HTTP Code Description Schema
200 The status of the device was successfully updated. Status
400 The request body is malformed or the state transition is invalid. See error for details. Error
404 The device 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 descriptor.

Name Description Schema
attributes
required
Attributes
device_identity
required
Identity data string
id
required
Hash created based on the device identity data. 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 the device 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 for admission process.

Name Description Schema
device_identity
required
The identity data of the device. string
key
required
Device public key string

Status

Admission status of the device.

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