Device authentication

Overview

An API for device authentication handling. Intended for use by devices.

Version information

Version : 1

URI scheme

Host : docker.mender.io
BasePath : /api/devices/v1/authentication
Schemes : HTTPS

Paths


Submit an authentication request

POST /auth_requests

Description

Issues an authentication token for use in device-facing API calls.

The device presents its unique identity data and public key, and signs the request with its private key. If the request is valid and the device is known to the system, a valid JWT authentication token is issued.

Note that the very first authentication request from a given device ('bootstrap' request) always results in 'HTTP 401 Unauthorized'. At the same time, the identity data is recorded for later inspection by the user, who then explicitly accepts or rejects the device via the web GUI (backed by the Device Admission Service). A subsequent authentication request will reflect this decision.

Note that in case of JWT expiration, the authentication request must be sent again.

Parameters

Type Name Description Schema Default
Header X-MEN-Signature
required
Request signature, computed as 'BASE64(SIGN(device_private_key, SHA256(request_body)))'.
Verified with the public key presented by the device.
string
Body auth_request
required
Authentication request. AuthRequest

Responses

HTTP Code Description Schema
200 Authentication successful - a new JWT is issued and returned.
The JWT is signed with the API's private key ('RS256' signing algorithm), and contains
the following standard claims:
'iss' - issuer
'exp' - expiry date
'sub' - subject (auto-generated device ID)
'jti' - token's unique identifier (tracked for the purpose of revocation)
No Content
400 Missing or malformed request params or body. See the error message for details. Error
401 The device cannot be granted authentication. There are multiple possible reasons, e.g.:
the device hasn't been accepted yet
the device has been explicitly rejected
* key/signature don't match

See the error message for details.
Error
500 Internal server error. Error

Example HTTP request

Request body
json :
{
  "application/json" : {
    "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"
  }
}

Example HTTP response

Response 200
json :
{
  "application/jwt" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9. eyJleHAiOjE0NzYxMTkxMzYsImp0aSI6Ijg1NGIzMTA5LTQ4NjItNGEyNS1h MWZiLWYxMTE2MWNlN2E4NCIsImlzcyI6Ik1lbmRlciIsInN1YiI6IjlmNzM2 YmNiMjhiZmFhOTg5YjVmNWUxNDA5ZGJmMGVhYzdhNjYxMjZiNjMyZDAzYWYwZ mUzNGFjMjhiZjRhNzIifQ. PArg_WuoQkOiJ4kDoHYbQRjnxykeF1lIlsgJfUryhivnip2AHz5bkxxaxF20X Tq9mIzSDonTSukfOtkaxJTZXjCMHjgh50iwa6_pUivIYWsIJW2O9t_M9T_SC- 7Xu7IhE_iKQFb2NXxVfAG4nZKrheUM4MJBt8SxCawT2EOPopiLeIC6MOFBu_s Pa9RsagKSZCRaLTBWVhmEGbfn19tLOX3Z06DZql61G-VY-YuyOlBjpEsCc4Hi A1cXIdncCZKugrONOa44_m4yx0VsgRg4jCd2VO-Is-A96Jw3zkZshoD2cPXVS KAhFdhHja447ftuYYRq9kIQghKi3hfsPgyFZQ"
}
Response 400
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 401
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

AuthRequest

Name Description Schema
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

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