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

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


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

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
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
500 Internal server error. Error

Example HTTP request

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

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)
ts
optional
Created timestamp string

Device

Name Description Schema
auth_sets
optional
< AuthSet > array
created_ts
optional
Created timestamp string
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

Status

Admission status of the device.

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