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 | Default |
---|---|---|---|---|
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 |
json :
{
"application/jwt" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9. eyJleHAiOjE0NzYxMTkxMzYsImlzcyI6Ik1lbmRlciIsIn N1YiI6Ijg1NGIzMTA5LTQ4NjItNGEyNS1hMWZiLWYxMTE2 MWNlN2E4NCIsInNjcCI6WyJtZW5kZXIuKiJdfQ. X7Ief4PhPLlR6mA2wh3G3K0Z2tud0rK1QJesxu52NfICSe ARmlujczs-_1YZxMwI0s-HgpXHbXIjaSVK80BjxjAM1rqp RGvgqSqG-dU5KmglDpAaTr4VaJci3VFPlVUVTRpI7bfqNM nKZtjmOUAGwjvroDUwX1RwayEmms-efGI"
}
json :
{
"application/json" : {
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"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 | 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 |
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 |
json :
{
"application/json" : {
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
GET /settings
Returns user settings.
Type | Name | Description | Schema | Default |
---|---|---|---|---|
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 |
json :
{
"application/json" : {
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
POST /users
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 |
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 |
json :
{
"application/json" : {
"email" : "user@acme.com",
"password" : "mypass1234"
}
}
json :
{
"application/json" : {
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"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 | Default |
---|---|---|---|---|
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 |
json :
{
"application/json" : {
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
GET /users/{id}
Returns user information.
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 |
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 |
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"
}
}
json :
{
"application/json" : {
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"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 | 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 |
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 |
json :
{
"application/json" : {
"email" : "new_email@acme.com"
}
}
json :
{
"application/json" : {
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
DELETE /users/{id}
Remove user information from the system.
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 |
HTTP Code | Description | Schema |
---|---|---|
204 | User removed. | No Content |
401 | The user cannot be granted authentication. | Error |
500 | Internal server error. | Error |
json :
{
"application/json" : {
"error" : "missing Authorization header",
"request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
}
json :
{
"application/json" : {
"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. Invalid characters are non-ascii and '+'. | string |
password required |
Password. | string |
Update user information.
Name | Description | Schema |
---|---|---|
email optional |
A unique email address. | string |
password optional |
Password. | string |