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

User administration and authentication

Overview

An API for user administration and user authentication handling. Intended for use by the web GUI. All responses from the API will contain 'X-MEN-RequestID' header with server-side generated request ID.

Version information

Version : 1

URI scheme

Host : hosted.mender.io
BasePath : /api/management/v1/useradm
Schemes : HTTPS

Consumes

  • application/json

Produces

  • application/json

Paths


Log in to Mender

POST /auth/login

Description

Accepts user credentials via standard Basic Auth, and returns a JWT token to be used for authentication in subsequent requests.

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' - unique, autogenerated user ID
'scp' - 'mender.*', allows access to all APIs/methods
string
400 Bad request, see error message for details. Error
401 Unauthorized. Error
500 Internal server error. Error

Produces

  • application/jwt
  • application/json

Tags

  • Management API

Security

Type Name
basic Login

Example HTTP response

Response 200
"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0NzYxMTkxMzYsImlzcyI6Ik1lbmRlciIsInN1YiI6Ijg1NGIzMTA5LTQ4NjItNGEyNS1hMWZiLWYxMTE2MWNlN2E4NCIsInNjcCI6WyJtZW5kZXIuKiJdfQ.X7Ief4PhPLlR6mA2wh3G3K0Z2tud0rK1QJesxu52NfICSeARmlujczs-_1YZxMwI0s-HgpXHbXIjaSVK80BjxjAM1rqpRGvgqSqG-dU5KmglDpAaTr4VaJci3VFPlVUVTRpI7bfqNMnKZtjmOUAGwjvroDUwX1RwayEmms-efGI"
Response 400
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 401
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Set user settings

POST /settings

Description

Create user settings or replace existing settings with provided object.

Parameters

Type Name Description Schema
Body settings
required
New user settings. Settings

Responses

HTTP Code Description Schema
201 User settings set. No Content
400 The request body is malformed. Error
401 The user cannot be granted authentication. Error
500 Internal server error. Error

Tags

  • Management API

Security

Type Name
apiKey ManagementJWT

Example HTTP response

Response 400
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 401
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Get user settings

GET /settings

Responses

HTTP Code Description Schema
200 Successful response - a user information is returned. Settings
401 The user cannot be granted authentication. Error
500 Internal server error. Error

Tags

  • Management API

Security

Type Name
apiKey ManagementJWT

Example HTTP response

Response 401
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Create a new user under the tenant owning the JWT.

POST /users

Parameters

Type Name Description Schema
Body user
required
New user data. UserNew

Responses

HTTP Code Description Schema
201 The user was successfully created.
Headers :
Location (string) : URI for the newly created 'User' resource.
No Content
400 The request body is malformed. Error
401 The user cannot be granted authentication. Error
422 The email address is duplicated or password is too short. Error
500 Internal server error. Error

Tags

  • Management API

Security

Type Name
apiKey ManagementJWT

Example HTTP request

Request body
{
  "email" : "user@acme.com",
  "password" : "mypass1234"
}

Example HTTP response

Response 400
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 401
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 422
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

List all users registered under the tenant owning the JWT.

GET /users

Responses

HTTP Code Description Schema
200 Successful response. < User > array
401 The user cannot be granted authentication. Error
500 Internal server error. Error

Tags

  • Management API

Security

Type Name
apiKey ManagementJWT

Example HTTP response

Response 401
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Get user information

GET /users/{id}

Parameters

Type Name Description Schema
Path id
required
User id. string

Responses

HTTP Code Description Schema
200 Successful response - a user information is returned. User
401 The user cannot be granted authentication. Error
404 The user was not found. Error
500 Internal server error. Error

Tags

  • Management API

Security

Type Name
apiKey ManagementJWT

Example HTTP response

Response 200
{
  "email" : "user@acme.com",
  "id" : "806603def19d417d004a4b67e",
  "created_ts" : "2020-07-06T15:04:49.114046203+02:00",
  "updated_ts" : "2020-07-07T01:04:49.114046203+02:00"
}
Response 401
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 404
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Update user information

PUT /users/{id}

Parameters

Type Name Description Schema
Path id
required
User id. string
Body update
required
Updated user data. UserUpdate

Responses

HTTP Code Description Schema
204 User information updated. No Content
400 The request body is malformed. Error
401 The user cannot be granted authentication. Error
404 The user does not exist. Error
422 The email address is duplicated or password is too short. Error
500 Internal server error. Error

Tags

  • Management API

Security

Type Name
apiKey ManagementJWT

Example HTTP request

Request body
{
  "email" : "new_email@acme.com"
}

Example HTTP response

Response 400
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 401
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 404
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 422
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Remove user from the system

DELETE /users/{id}

Parameters

Type Name Description Schema
Path id
required
User id. string

Responses

HTTP Code Description Schema
204 User removed. No Content
401 The user cannot be granted authentication. Error
500 Internal server error. Error

Tags

  • Management API

Security

Type Name
apiKey ManagementJWT

Example HTTP response

Response 401
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "missing Authorization header",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Definitions

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

Settings

User settings.

Type : object

User

User descriptor.

Name Description Schema
created_ts
optional
Server-side timestamp of the user creation. string (date-time)
email
required
A unique email address. string
id
required
User Id. string
updated_ts
optional
Server-side timestamp of the last user information update. string (date-time)

UserNew

New user descriptor.

Name Description Schema
email
required
A unique email address. Invalid characters are non-ascii and '+'. string
password
required
Password. string

UserUpdate

Update user information.

Name Description Schema
email
optional
A unique email address. string
password
optional
Password. string

Security

Login

Type : basic

ManagementJWT

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

Type : apiKey
Name : Authorization
In : HEADER