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

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)