Back to top

User Management API

Endpoints to perform user and session management

Auth

Session management

Create session
POST/

Authenticate with the system, returning a session token to be used with API

Example URI

POST /
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "username": "testadm",
  "passwd": "admin"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "jwt": "eyJhb ... pXVCJ9.eyJpc ... 3MIn0.j1iYHo ... yae88PvodY"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 400,
  "message": "invalid mimetype"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 400,
  "message": "missing passswd"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 400,
  "message": "missing username"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "not authorized",
  "status": 401
}

Known users manipulation

List known users
GET/user

Lists all users known to the platform

Example URI

GET /user
Request
HideShow
Headers
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "users": [
    {
      "created_by": "0",
      "created_date": "2018-01-03 12:49:25.717374",
      "email": "admin@noemail.com",
      "id": "1",
      "name": "Admin (superuser)",
      "profile": "testadm",
      "service": "admin",
      "username": "testadm"
    },
    {
      "created_by": "1",
      "created_date": "2018-01-04 13:09:03.568749",
      "email": "test@noemail.com",
      "id": "2",
      "name": "test",
      "profile": "testuser",
      "service": "test",
      "username": "test"
    }
  ]
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Unauthorized"
}

Register a new user
POST/user

Creates a new user, assigning it a service.

Service is the token that associates the user with the set of devices and flows it has access to.

Example URI

POST /user
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer JWT
Body
{
  "username": "test",
  "service": "test",
  "email": "test@noemail.com",
  "name": "test",
  "profile": "testuser"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "user": {
      "id": "2",
      "name": "test",
      "username": "test",
      "service": "test",
      "email": "test@noemail.com",
      "profile": "testuser",
      "created_date": "2018-01-04 13:09:03.568749",
      "created_by": "0"
    },
    "groups": [
      "testuser"
    ],
    "could not add": [],
    "message": "user created"
  }
]
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Unauthorized"
}

Individual user settings

Access a user’s authorization and identification information

Get user info
GET/user/

Retrieves all information from a specific registered user

Example URI

GET /user/
Request
HideShow
Headers
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "user": {
    "created_by": "0",
    "created_date": "2018-01-03 12:49:25.717374",
    "email": "testadm@noemail.com",
    "id": "1",
    "name": "testadm",
    "profile": "testadm",
    "service": "admin",
    "username": "testadm"
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Unauthorized"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "No user found with this ID",
  "status": 404
}

Update user info
PUT/user/

Replaces user information. Fields or attributes that are not informed will revert to their defaults.

Example URI

PUT /user/
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer JWT
Body
{
  "service": "test",
  "email": "test_new@noemail.com",
  "name": "test"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "ok",
  "status": 200
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Unauthorized"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Unknown user id",
  "status": 404
}

Remove user
DELETE/user/

Removes a user from the system

Example URI

DELETE /user/
Request
HideShow
Headers
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "User removed",
  "status": 200
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Unauthorized"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "User was not found",
  "status": 200
}

List tenant services

List all known tenants in dojot

This is an internal call used for debugging, and for service initialization procedure. Hence only calls issued from within the platform will be accepted.

List tenants
GET/admin/tenants

List all tenants currently configured in dojot

Example URI

GET /admin/tenants
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
      "tenants": [
        "admin",
        "test"
      ]
    }
FORMAT: 1A

CRUD Permissions and Group

Permissions management

Get a permission
GET/pap/permission/{id}

Example URI

GET /pap/permission/1
URI Parameters
HideShow
id
integer (required) Example: 1

The permission ID

Request
HideShow
Headers
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 131,
  "path": "/devices/info/\\*",
  "method": "POST|PUT|DELETE",
  "permission": "permit",
  "type": "api"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No permission found with this ID"
}

Update a permission
PUT/pap/permission/{id}

Example URI

PUT /pap/permission/1
URI Parameters
HideShow
id
integer (required) Example: 1

The permission ID

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer JWT
Body
{
  "path": "/devices/info/\\*",
  "method": "POST|PUT|DELETE",
  "permission": "permit",
  "name": "sample_permission"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 200,
  "message": "ok"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No permission with found this ID"
}

Remove a permission
DELETE/pap/permission/{id}

Example URI

DELETE /pap/permission/1
URI Parameters
HideShow
id
integer (required) Example: 1

The permission ID

Request
HideShow
Headers
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 200,
  "message": "ok"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No permission found with this ID"
}
Response  405
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 405,
  "message": "Can't delete a system permission"
}

Group creation

Create a new group
POST/pap/group

Example URI

POST /pap/group
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer JWT
Body
{
  "name": "group1",
  "description": "a fine group"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 200,
  "id": 3
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "Group named group1 already exists"
}

Search Groups
GET/pap/group?name={name}

Example URI

GET /pap/group?name=testadm
URI Parameters
HideShow
name
string (optional) Example: testadm

a group name, or part of a group name.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "groups": [
    {
      "id": 3,
      "name": "testadm",
      "description": "Full privilege group"
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No group found with these filters"
}

Group management

Get a group
GET/pap/group/{id}

Example URI

GET /pap/group/1
URI Parameters
HideShow
id
integer (required) Example: 1

group ID

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 3,
  "name": "group1",
  "description": null
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No group found with this ID"
}

Update a group
PUT/pap/group/{id}

Example URI

PUT /pap/group/1
URI Parameters
HideShow
id
integer (required) Example: 1

group ID

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer JWT
Body
{
  "name": "testadm",
  "description": "projectX"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 200,
  "message": "ok"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No group found with this ID"
}

Remove a group
DELETE/pap/group/{id}

Example URI

DELETE /pap/group/1
URI Parameters
HideShow
id
integer (required) Example: 1

group ID

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 200,
  "message": "ok"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
        "status": 404,
        "message": "No group found with this ID"
    }
FORMAT: 1A

Relationship management

Manage relationships between users and groups

Add user to group
POST/pap/usergroup/{user_id}/{group_id}

Example URI

POST /pap/usergroup/1/101
URI Parameters
HideShow
user_id
string (required) Example: 1

The user ID

group_id
string (required) Example: 101

The group ID

Request
HideShow
Headers
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 200,
  "message": "ok"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No user found with this ID"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No group found with this ID"
}

Remove a user from group
DELETE/pap/usergroup/{user_id}/{group_id}

Example URI

DELETE /pap/usergroup/1/101
URI Parameters
HideShow
user_id
string (required) Example: 1

The user ID

group_id
string (required) Example: 101

The group ID

Request
HideShow
Headers
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 200,
  "message": "ok"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No user found with this ID"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No group found with this ID"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 400,
  "message": "Can't remove user. A user must always be in one role group"
}

Manage relationships between users and permissions

Give a permission to a user
POST/pap/userpermissions/{user_id}/{permission_id}

Example URI

POST /pap/userpermissions/1/201
URI Parameters
HideShow
user_id
string (required) Example: 1

The user ID

permission_id
string (required) Example: 201

The permission ID to be changed

Request
HideShow
Headers
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 200,
  "message": "ok"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No user found with this ID"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No permission found with this ID"
}

Revoke a user permission
DELETE/pap/userpermissions/{user_id}/{permission_id}

Example URI

DELETE /pap/userpermissions/1/201
URI Parameters
HideShow
user_id
string (required) Example: 1

The user ID

permission_id
string (required) Example: 201

The permission ID to be changed

Request
HideShow
Headers
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 200,
  "message": "ok"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No user found with this ID"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No permission found with this ID"
}

Manage relationships between group and permissions

Give a permission to a group
POST/pap/grouppermissions/{group_id}/{permission_id}

Example URI

POST /pap/grouppermissions/101/201
URI Parameters
HideShow
group_id
string (required) Example: 101

The group ID

permission_id
string (required) Example: 201

The permission ID to be changed

Request
HideShow
Headers
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 200,
  "message": "ok"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No group found with this ID"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No permission found with this ID"
}

Revoke a group permission
DELETE/pap/grouppermissions/{group_id}/{permission_id}

Example URI

DELETE /pap/grouppermissions/101/201
URI Parameters
HideShow
group_id
string (required) Example: 101

The group ID

permission_id
string (required) Example: 201

The permission ID to be changed

Request
HideShow
Headers
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 200,
  "message": "ok"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No group found with this ID"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
        "status": 404,
        "message": "No permission found with this ID"
    }
FORMAT: 1A

Reports

User direct permissions

Retrieve user direct permissions
GET/pap/user/{user}/directpermissions

Example URI

GET /pap/user/testadm/directpermissions
URI Parameters
HideShow
user
string (required) Example: testadm

user being requested.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "permissions": [
    {
      "id": 130,
      "path": "/exceptional/path\\*",
      "method": "POST|PUT|DELETE",
      "permission": "permit"
    },
    {
      "id": 136,
      "path": "/cantaccess",
      "method": "\\*",
      "permission": "deny"
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No user found with tihs username or ID"
}

All user permissions

Retrieve all user permissions
GET/pap/user/{user}/allpermissions

Example URI

GET /pap/user/testadm/allpermissions
URI Parameters
HideShow
user
string (required) Example: testadm

user being requested.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "permissions": [
    {
      "id": 131,
      "path": "/devices/info/\\*",
      "method": "POST|PUT|DELETE",
      "permission": "permit"
    },
    {
      "id": 132,
      "path": "/auth/user",
      "method": "\\*",
      "permission": "deny"
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No user found with tihs username or ID"
}

User groups

Retrieve all user groups
GET/pap/user/{user}/groups

Example URI

GET /pap/user/testadm/groups
URI Parameters
HideShow
user
string (required) Example: testadm

user being requested.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "groups": [
    {
      "id": 3,
      "name": "group1"
    },
    {
      "id": 4,
      "name": "testadm"
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No user found with tihs username or ID"
}

Group permissions

Retrieve all group permissions
GET/pap/group/{group}/permissions

Example URI

GET /pap/group/users/permissions
URI Parameters
HideShow
group
string (required) Example: users

user being requested.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "permissions": [
    {
      "id": 131,
      "path": "/devices/info/\\*",
      "method": "POST|PUT|DELETE",
      "permission": "permit"
    },
    {
      "id": 132,
      "path": "/auth/user",
      "method": "\\*",
      "permission": "deny"
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No group found with this name or ID"
}

Group users

Retrieve all users from a group
GET/pap/group/{group}/users

Example URI

GET /pap/group/users/users
URI Parameters
HideShow
group
string (required) Example: users

user being requested.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "users": [
    {
      "id": 3252352,
      "name": "Alexandre Vasconcellos",
      "email": "alex@noemai.com",
      "username": "aexv",
      "service": "user"
    },
    {
      "id": 1124235532,
      "name": "John Wayne",
      "email": "wayne@company.com",
      "username": "johnw",
      "service": "user"
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "status": 404,
  "message": "No group found with this name or ID"
}

Generated by aglio on 13 Mar 2019