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

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