You are browsing documentation for a version other than the latest stable release. Switch to the latest stable release, 2.2.
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 : 1
Host : docker.mender.io
BasePath : /api/management/v1/useradm
Schemes : HTTPS
POST /auth/login
Accepts user credentials via standard Basic Auth, and returns a JWT token to be used for authentication in subsequent requests.
Type | Name | Description | Schema |
---|---|---|---|
Header | Authorization required |
Standard Basic Auth header, based on user's credentials. | string |
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 |
{
"application/jwt" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9. eyJleHAiOjE0NzYxMTkxMzYsImlzcyI6Ik1lbmRlciIsIn N1YiI6Ijg1NGIzMTA5LTQ4NjItNGEyNS1hMWZiLWYxMTE2 MWNlN2E4NCIsInNjcCI6WyJtZW5kZXIuKiJdfQ. X7Ief4PhPLlR6mA2wh3G3K0Z2tud0rK1QJesxu52NfICSe ARmlujczs-_1YZxMwI0s-HgpXHbXIjaSVK80BjxjAM1rqp RGvgqSqG-dU5KmglDpAaTr4VaJci3VFPlVUVTRpI7bfqNM nKZtjmOUAGwjvroDUwX1RwayEmms-efGI"
}
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
POST /settings
Create user settings or replace existing settings with provided object.
Type | Name | Description | Schema |
---|---|---|---|
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 |
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 |
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
GET /settings
Returns user settings.
Type | Name | Description | Schema |
---|---|---|---|
Header | Authorization required |
Contains the JWT token issued by the User Administration and Authentication Service. | string (Bearer [token]) |
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 |
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
POST /users
Type | Name | Description | Schema |
---|---|---|---|
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 |
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 |
{
"email" : "user@acme.com",
"password" : "mypass1234"
}
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
GET /users
Returns a non-paged collection of users information.
Type | Name | Description | Schema |
---|---|---|---|
Header | Authorization required |
Contains the JWT token issued by the User Administration and Authentication Service. | string (Bearer [token]) |
HTTP Code | Description | Schema |
---|---|---|
200 | Successful response. | < User > array |
401 | The user cannot be granted authentication. | Error |
500 | Internal server error. | Error |
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
GET /users/{id}
Returns user information.
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 |
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 |
{
"email" : "user@acme.com",
"id" : "806603def19d417d004a4b67e",
"created_ts" : "2016-10-03T16:58:51.639Z",
"updated_ts" : "2016-10-04T11:33:66.611Z"
}
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
PUT /users/{id}
Update user email or change user password.
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 |
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 |
{
"email" : "new_email@acme.com"
}
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
DELETE /users/{id}
Remove user information from the system.
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 |
HTTP Code | Description | Schema |
---|---|---|
204 | User removed. | No Content |
401 | The user cannot be granted authentication. | Error |
500 | Internal server error. | Error |
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
{
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
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 |
User settings.
Type : object
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) |
New user descriptor.
Name | Description | Schema |
---|---|---|
email required |
A unique email address. | string |
password required |
Password. | string |
Update user information.
Name | Description | Schema |
---|---|---|
email optional |
A unique email address. | string |
password optional |
Password. | string |