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 : 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.

Parameters

Type Name Description Schema Default
Header Authorization
required		 Standard Basic Auth header, based on user's credentials. 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
 'scp' - 'mender.*', allows access to all APIs/methods		 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",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 401
json :
{
  "application/json" : {
    "error" : "missing Authorization header",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "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 Default
Header Authorization
required		 Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
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

Example HTTP response

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

Get user settings

GET /settings

Description

Returns user settings.

Parameters

Type Name Description Schema Default
Header Authorization
required		 Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])

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

Example HTTP response

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

Create user

POST /users

Parameters

Type Name Description Schema Default
Header Authorization
required		 Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
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

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",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 401
json :
{
  "application/json" : {
    "error" : "missing Authorization header",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 422
json :
{
  "application/json" : {
    "error" : "missing Authorization header",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "missing Authorization header",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

List users

GET /users

Description

Returns a non-paged collection of users information.

Parameters

Type Name Description Schema Default
Header Authorization
required		 Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])

Responses

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

Example HTTP response

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

Get user information

GET /users/{id}

Description

Returns user information.

Parameters

Type Name Description Schema Default
Header Authorization
required		 Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
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

Example HTTP response

Response 200
json :
{
  "application/json" : {
    "email" : "user@acme.com",
    "id" : "806603def19d417d004a4b67e",
    "created_ts" : "2016-10-03T16:58:51.639Z",
    "updated_ts" : "2016-10-04T11:33:66.611Z"
  }
}
Response 401
json :
{
  "application/json" : {
    "error" : "missing Authorization header",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 404
json :
{
  "application/json" : {
    "error" : "missing Authorization header",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "missing Authorization header",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Update user information

PUT /users/{id}

Description

Update user email or change user password.

Parameters

Type Name Description Schema Default
Header Authorization
required		 Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path id
required		 User id. string
Body user_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

Example HTTP request

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

Example HTTP response

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

Remove user from the system

DELETE /users/{id}

Description

Remove user information from the system.

Parameters

Type Name Description Schema Default
Header Authorization
required		 Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
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

Example HTTP response

Response 401
json :
{
  "application/json" : {
    "error" : "missing Authorization header",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "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