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

Device authentication

Overview

An API for device authentication handling. This API replaces first version of the device authentication management API and device admission management API. First version of the device authentication management API and device admission management API are deprecated and will be removed with the next Mender release. You can still find information about first version of the device authentication service API at https://docs.mender.io/1.6/apis/management-apis/device-authentication and about device admission API at https://docs.mender.io/1.6/apis/management-apis/device-admission.

Version information

Version : 2

URI scheme

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

Paths


Submit a preauthorized device.

POST /devices

Description

Adds a given device/authentication data set in the 'preauthorized' state. The device identity data set must not yet exist in the DB (regardless of status).

When the device requests authentication from deviceauth the next time, it will be issued a token without further user intervention.

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

Responses

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

Example HTTP request

Request body
json :
{
  "application/json" : {
    "identity_data" : {
      "application/json" : {
        "mac" : "00:01:02:03:04:05",
        "sku" : "My Device 1",
        "sn" : "SN1234567890"
      }
    },
    "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, sorted by creation date, 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"
Query status
optional
Device status filter. If not specified, all devices are listed. enum (pending, accepted, rejected, preauthorized)

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 and the device is 'preauthorized' then 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

Get the device authentication set status

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

Description

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

Responses

HTTP Code Description Schema
200 successful response - the device's authentication set 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"
  }
}

Update the device authentication set status

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

Description

Sets the status of a authentication data set of selected value. 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 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
identity_data
optional
IdentityData
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
identity_data
optional
IdentityData
status
optional
enum (pending, accepted, rejected, preauthorized)
updated_ts
optional
Updated timestamp string

Error

Error descriptor

Name Description Schema
error
optional
Description of the error string

IdentityData

Device identity attributes, in the form of a JSON structure.

The attributes are completely vendor-specific, the provided ones are just an example. In reference implementation structure contains vendor-selected fields, such as MACs, serial numbers, etc.

Name Description Schema
mac
optional
MAC address. string
sku
optional
Stock keeping unit. string
sn
optional
Serial number. string

Limit

Limit definition

Name Description Schema
limit
required
integer

PreAuthSet

Name Description Schema
identity_data
required
IdentityData
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)