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

1.7 APIs Management APIs User administration and authentication

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

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