Device authentication

Overview

An API for device authentication handling.

Version information

Version : 1

URI scheme

Host : mender-device-auth:8080
BasePath : /api/management/v1/devauth/
Schemes : HTTP

Paths

Submit a preauthorized device.

POST /devices

Description

Adds a given device/authentication data set in the 'preauthorized' state. Designed to be called from admission, with precomputed device_id and auth_set_id.

Parameters

Type Name Description Schema Default
Header Authorization
required		 Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Body pre_auth_request
required		 Preauthentication request. PreAuthRequest

Responses

HTTP Code Description Schema
201 Device submitted. No Content
400 Missing/malformed request params. Error
409 Device already exists. Error
500 Unexpected error Error

Example HTTP request

Request body
json :
{
  "application/json" : {
    "device_id" : "f7881e82-0492-49fb-b459-795654e7188a",
    "auth_set_id" : "a7881e82-0492-49fb-b459-795654e7188f",
    "id_data" : "{\"mac\":\"00:01:02:03:04:05\"}",
    "pubkey" : "-----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"
  }
}

Get a list of tenant's devices.

GET /devices

Description

Provides a list of tenant's devices, with optional device status filter.

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		 Results page number number(integer) "1"
Query per_page
optional		 Number of results per page number(integer) "20"

Responses

HTTP Code Description Schema
200 An array of devices.
Headers :
Link (string) : Standard header, we support 'first', 'next', and 'prev'.		 < Device > array
400 Missing/malformed request params. Error
500 Unexpected error Error

Get a count of devices, optionally filtered by status.

GET /devices/count

Description

Provides a list of devices, optionally filtered by 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 status
optional		 Device status filter, one of 'pending', 'accepted', 'rejected'. Default is 'all devices'. string

Responses

HTTP Code Description Schema
200 Device count. Count
400 Missing/malformed request params. Error
500 Unexpected error Error

Example HTTP response

Response 200
json :
{
  "count" : "42"
}

Get a particular device.

GET /devices/{id}

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 string

Responses

HTTP Code Description Schema
200 Device found. Device
404 Device not found. Error
500 Unexpected error Error

Decommission device

DELETE /devices/{id}

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. string

Responses

HTTP Code Description Schema
204 Device decommissioned. No Content
404 Device not found Error
500 Internal server error. Error

Remove the device authentication set

DELETE /devices/{id}/auth/{aid}

Description

Removes the device authentication set. Removing 'accepted' authentication set is equivalent to rejecting device and removing authentication set. If there is only one authentication set for the device, the device will also be deleted.

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 aid
required		 Authentication data set identifier. string
Path id
required		 Device identifier. string

Responses

HTTP Code Description Schema
204 Device authentication set deleted. No Content
404 Device authentication set not found Error
500 Internal server error. Error

Update the device authentication set status

PUT /devices/{id}/auth/{aid}/status

Description

Sets the status of a authentication data set of selected value.

All possible transitions are valid.

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 aid
required		 Authentication data set identifier. string
Path id
required		 Device identifier. string
Body status
required		 New status. Status

Responses

HTTP Code Description Schema
204 The device authentication data set status was successfully updated. No Content
400 Bad request. Error
404 The device was not found. Error
422 Request cannot be fulfilled e.g. due to exceeded limit on maximum accepted devices (see error message). Error
500 Internal server error. Error

Example HTTP request

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

Obtain limit of accepted devices.

GET /limits/max_devices

Parameters

Type Name Description Schema Default
Header Authorization
required		 Contains the JWT token issued by the User Administration and
Authentication Service.		 string(Bearer [token])

Responses

HTTP Code Description Schema
200 Usage statistics and limits. Limit
500 Internal server error. Error

Example HTTP response

Response 200
json :
{
  "application/json" : {
    "limit" : 123
  }
}

Delete device token

DELETE /tokens/{id}

Description

Deletes the token, effectively revoking it. The device must apply for a new one with a new authentication request. The token 'id' corresponds to the standard 'jti' claim.

Parameters

Type Name Description Schema Default
Path id
required		 Unique token identifier('jti'). string

Responses

HTTP Code Description Schema
204 The token was successfully deleted. No Content
404 The token was not found. Error
500 Internal server error. Error

Definitions

AuthSet

Authentication data set

Name Description Schema
id
optional		 Authentication data set ID. string
id_data
optional		 Vendor-specific JSON representation of device identity, encrypted with the tenant's public key.
In reference implementation, it is a JSON structure with vendor-selected fields, such as MACs, serial numbers, etc.		 string
pubkey
optional		 The device's public key, generated by the device or pre-provisioned by the vendor. string
status
optional		 enum (pending, accepted, rejected, preauthorized)
ts
optional		 Created timestamp string

Count

Counter type

Name Description Schema
count
optional		 The count of requested items. integer

Device

Name Description Schema
auth_sets
optional		 < AuthSet > array
created_ts
optional		 Created timestamp string
decommissioning
optional		 Devices that are part of ongoing decomissioning process will return True boolean
id
optional		 Mender assigned Device ID. string
id_data
optional		 Vendor-specific JSON representation of device identity, encrypted with the tenant's public key.
In reference implementation, it is a JSON structure with vendor-selected fields, such as MACs, serial numbers, etc.		 string
updated_ts
optional		 Updated timestamp string

Error

Error descriptor

Name Description Schema
error
optional		 Description of the error string

Limit

Limit definition

Name Description Schema
limit
required		 integer

PreAuthRequest

Name Description Schema
auth_set_id
required		 Precomputed auth set ID. string
device_id
required		 Precomputed device ID. string
id_data
required		 Vendor-specific JSON representation of the device identity data (MACs, serial numbers, etc.). string
pubkey
required		 The device's public key, generated by the device or pre-provisioned by the vendor. string

Status

Admission status of the device.

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