You are browsing documentation for a version other than the latest stable release. Switch to the latest stable release, 2.2.
An API for device authentication handling. This API version has been deprecated and will be removed in Mender 1.8 release.
Version : 1
Host : mender-device-auth:8080
BasePath : /api/management/v1/devauth/
Schemes : HTTP
POST /devices
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.
Type | Name | Description | Schema |
---|---|---|---|
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 |
HTTP Code | Description | Schema |
---|---|---|
201 | Device submitted. | No Content |
400 | Missing/malformed request params. | Error |
409 | Device already exists. | Error |
500 | Unexpected error | Error |
{
"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-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzogVU7RGDilbsoUt/DdH
VJvcepl0A5+xzGQ50cq1VE/Dyyy8Zp0jzRXCnnu9nu395mAFSZGotZVr+sWEpO3c
yC3VmXdBZmXmQdZqbdD/GuixJOYfqta2ytbIUPRXFN7/I7sgzxnXWBYXYmObYvdP
okP0mQanY+WKxp7Q16pt1RoqoAd0kmV39g13rFl35muSHbSBoAW3GBF3gO+mF5Ty
1ddp/XcgLOsmvNNjY+2HOD5F/RX0fs07mWnbD7x+xz7KEKjF+H7ZpkqCwmwCXaf0
iyYyh1852rti3Afw4mDxuVSD7sd9ggvYMc0QHIpQNkD4YWOhNiE1AB0zH57VbUYG
UwIDAQAB
-----END PUBLIC KEY-----
"
}
GET /devices
Provides a list of tenant's devices, with optional device status filter.
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 |
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 /devices/count
Provides a list of devices, optionally filtered by status.
Type | Name | Description | Schema |
---|---|---|---|
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 |
HTTP Code | Description | Schema |
---|---|---|
200 | Device count. | Count |
400 | Missing/malformed request params. | Error |
500 | Unexpected error | Error |
{
"count" : "42"
}
GET /devices/{id}
Type | Name | Description | Schema |
---|---|---|---|
Header | Authorization required |
Contains the JWT token issued by the User Administration and Authentication Service. | string (Bearer [token]) |
Path | id required |
Device identifier | string |
HTTP Code | Description | Schema |
---|---|---|
200 | Device found. | Device |
404 | Device not found. | Error |
500 | Unexpected error | Error |
DELETE /devices/{id}
Type | Name | Description | Schema |
---|---|---|---|
Header | Authorization required |
Contains the JWT token issued by the User Administration and Authentication Service. | string (Bearer [token]) |
Path | id required |
Device identifier. | string |
HTTP Code | Description | Schema |
---|---|---|
204 | Device decommissioned. | No Content |
404 | Device not found | Error |
500 | Internal server error. | Error |
DELETE /devices/{id}/auth/{aid}
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.
Type | Name | Description | Schema |
---|---|---|---|
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 |
HTTP Code | Description | Schema |
---|---|---|
204 | Device authentication set deleted. | No Content |
404 | Device authentication set not found | Error |
500 | Internal server error. | Error |
PUT /devices/{id}/auth/{aid}/status
Sets the status of a authentication data set of selected value.
All possible transitions are valid.
Type | Name | Description | Schema |
---|---|---|---|
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 |
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 |
{
"status" : "accepted"
}
GET /limits/max_devices
Type | Name | Description | Schema |
---|---|---|---|
Header | Authorization required |
Contains the JWT token issued by the User Administration and Authentication Service. |
string (Bearer [token]) |
HTTP Code | Description | Schema |
---|---|---|
200 | Usage statistics and limits. | Limit |
500 | Internal server error. | Error |
{
"limit" : 123
}
DELETE /tokens/{id}
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.
Type | Name | Description | Schema |
---|---|---|---|
Path | id required |
Unique token identifier('jti'). | string |
HTTP Code | Description | Schema |
---|---|---|
204 | The token was successfully deleted. | No Content |
404 | The token was not found. | Error |
500 | Internal server error. | Error |
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 (datetime) |
Counter type
Name | Description | Schema |
---|---|---|
count optional |
The count of requested items. | integer |
Name | Description | Schema |
---|---|---|
auth_sets optional |
< AuthSet > array | |
created_ts optional |
Created timestamp | string (datetime) |
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 (datetime) |
Error descriptor
Name | Description | Schema |
---|---|---|
error optional |
Description of the error | string |
Limit definition
Name | Schema |
---|---|
limit required |
integer |
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 |
Admission status of the device.
Name | Schema |
---|---|
status required |
enum (pending, accepted, rejected) |