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

Device authentication

Overview

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

Version information

Version : 1

URI scheme

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

Consumes

  • application/json

Produces

  • application/json

Paths


Submit an authentication request

POST /auth_requests

Description

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.

Unless the device is pre-authorized, the very first authentication request from a device will always result in a 'HTTP 401 Unauthorized' response. At the same time, the identity data is recorded for later inspection by the user, who can then explicitly accepts or rejects the device via the web GUI. A subsequent authentication request will reflect this decision.

Note that when the JWT expires, the device must renew the JWT by sending a new authentication request.

Parameters

Type Name Description Schema
Header X-MEN-Signature
required
Request signature.

The request signature depends on the public key submitted in the
AuthRequest. A summary of signature algorithms and format follows:

| Type | Digest | Format | Algorithm |
|------------|---------------------|--------------------------|--------------|
| RSA | SHA256(AuthRequest) | Base64(Signature) | [RFC2313] |
| ECDSA | SHA256(AuthRequest) | Base64(ASN.1(SEQ{R, S})) | [ANSI x9.62] |
| ED25519 | AuthRequest | Base64(Signature) | [RFC8032] |
Remark:
For ECDSA, the signature constitutes two integers (R and S)
in which case the binary signature is taken as the ASN.1 sequence of
the two numbers in the given order.
string
Body AuthRequest
required
Authentication request. AuthRequest

Responses

HTTP Code Description Schema
200 Authentication successful - a new JWT is issued and returned. string
400 Missing or malformed request parameters or body. Error
401 The device cannot be granted authentication. See the error message for details. Error
500 Internal server error. Error

Produces

  • application/json
  • application/jwt

Tags

  • Device API

Security

Type Name
apiKey DeviceJWT

Example HTTP request

Request body
{
  "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
"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0NzYxMTkxMzYsImp0aSI6Ijg1NGIzMTA5LTQ4NjItNGEyNS1hMWZiLWYxMTE2MWNlN2E4NCIsImlzcyI6Ik1lbmRlciIsInN1YiI6IjlmNzM2YmNiMjhiZmFhOTg5YjVmNWUxNDA5ZGJmMGVhYzdhNjYxMjZiNjMyZDAzYWYwZmUzNGFjMjhiZjRhNzIifQ.PArg_WuoQkOiJ4kDoHYbQRjnxykeF1lIlsgJfUryhivnip2AHz5bkxxaxF20XTq9mIzSDonTSukfOtkaxJTZXjCMHjgh50iwa6_pUivIYWsIJW2O9t_M9T_SC-7Xu7IhE_iKQFb2NXxVfAG4nZKrheUM4MJBt8SxCawT2EOPopiLeIC6MOFBu_sPa9RsagKSZCRaLTBWVhmEGbfn19tLOX3Z06DZql61G-VY-YuyOlBjpEsCc4HiA1cXIdncCZKugrONOa44_m4yx0VsgRg4jCd2VO-Is-A96Jw3zkZshoD2cPXVSKAhFdhHja447ftuYYRq9kIQghKi3hfsPgyFZQ\n"
Response 400
{
  "error" : "missing required parameter: id_data",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188f"
}
Response 401
{
  "error" : "device unauthorized",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "internal error",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188d"
}

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 (PEM encoding), generated by the device or pre-provisioned by the vendor. Currently supported public algorithms are: RSA, ED25519 and ECDSA. string
tenant_token
optional
Tenant token. 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

Security

DeviceJWT

API token issued by Device Authentication service. Format: 'Authorization: Bearer [JWT]'

Type : apiKey
Name : Authorization
In : HEADER