User administration and authentication

Overview

An API for user administration and user authentication handling. Intended for use by the web GUI.

Version information

Version : 1

URI scheme

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

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.

When the backend is started for the first time (no users yet), the credentials can be omitted. A special-purpose token will be issued, allowing only the first-time user creation.

Parameters

Type Name Description Schema Default
Header Authorization
optional
Standard Basic Auth header, based on user's credentials.
If it's omitted - a valid token will be issued only when there are
no users defined yet in the database.
string

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

A custom 'scp' (scopes) claim is added to distinguish between a regular token and a first-time user
creation token:
'scp' : ['mender.'] - regular token
'scp' : ['mender.users.create.initial'] - first-time user creation token
No Content
400 Bad request, see error message for details. Error
401 Unauthorized. Error
500 Internal server error. Error

Example HTTP response

Response 200
json :
{
  "application/jwt" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9. eyJleHAiOjE0NzYxMTkxMzYsImlzcyI6Ik1lbmRlciIsIn N1YiI6Ijg1NGIzMTA5LTQ4NjItNGEyNS1hMWZiLWYxMTE2 MWNlN2E4NCIsInNjcCI6WyJtZW5kZXIuKiJdfQ. X7Ief4PhPLlR6mA2wh3G3K0Z2tud0rK1QJesxu52NfICSe ARmlujczs-_1YZxMwI0s-HgpXHbXIjaSVK80BjxjAM1rqp RGvgqSqG-dU5KmglDpAaTr4VaJci3VFPlVUVTRpI7bfqNM nKZtjmOUAGwjvroDUwX1RwayEmms-efGI"
}
Response 400
json :
{
  "application/json" : {
    "error" : "missing Authorization header"
  }
}
Response 401
json :
{
  "application/json" : {
    "error" : "missing Authorization header"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "missing Authorization header"
  }
}

Create the initial Mender user

POST /users/inital

Description

Creates the initial Mender user, provided that:

  • the users database is empty
  • a valid JWT token is presented (scope: 'mender.users.create.initial')

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued upon login. string(Bearer [token])
Body user
required
New user descriptor. User

Responses

HTTP Code Description Schema
201 Successful response.
Headers :
Location (string) : URL of the newly created user.
No Content
400 Bad request, see error message for details. Error
401 Unauthorized. Error
403 Forbidden. Error
500 Internal server error. Error

Produces

  • application/json

Example HTTP request

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

Example HTTP response

Response 400
json :
{
  "application/json" : {
    "error" : "missing Authorization header"
  }
}
Response 401
json :
{
  "application/json" : {
    "error" : "missing Authorization header"
  }
}
Response 403
json :
{
  "application/json" : {
    "error" : "missing Authorization header"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "missing Authorization header"
  }
}

Definitions

Error

Error descriptor.

Name Description Schema
error
optional
Description of the error. string

User

New user descriptor.

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