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": "admin",
  "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": "admin",
      "service": "admin",
      "username": "admin"
    },
    {
      "created_by": "1",
      "created_date": "2018-01-04 13:09:03.568749",
      "email": "test@noemail.com",
      "id": "2",
      "name": "test",
      "profile": "user",
      "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": "user"
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "user": {
      "id": "2",
      "name": "test",
      "username": "test",
      "service": "test",
      "email": "test@noemail.com",
      "profile": "user",
      "created_date": "2018-01-04 13:09:03.568749",
      "created_by": "0"
    },
    "groups": [
      "user"
    ],
    "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": "admin@noemail.com",
    "id": "1",
    "name": "Admin (superuser)",
    "profile": "admin",
    "service": "admin",
    "username": "admin"
  }
}

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",
  "profile": "user"
}

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 creation and search ¶

Create a new permission
POST`/pap/permission`

Notice that regular expressions can be used on the ‘path’ and ‘method’ fields, and all slashes that serve to escape some characters (’*’, in the example) must also be escaped

Example URI

POST /pap/permission

Request

HideShow

Headers

Content-Type: application/json
Authorization: Bearer JWT

Body

{
  "path": "/devices/info/\\*",
  "method": "POST|PUT|DELETE",
  "permission": "permit",
  "name": "device_write_operations"
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "status": 200,
  "id": 131
}

Search permission
GET`/pap/permission?{path,method,permission}`

Example URI

GET /pap/permission?\/devices\/info&POST&permit

URI Parameters

HideShow

path: string (optional) Example: \/devices\/info
a path string.
method: enum (optional) Example: POST
one HTTP method.
permission: enum (optional) Example: permit
“permit” or “deny”.

Request

HideShow

Headers

Content-Type: application/json
Authorization: Bearer JWT

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "permissions": [
    {
      "id": 131,
      "path": "/devices/info/\\*",
      "method": "POST|PUT|DELETE",
      "permission": "permit"
    }
  ]
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  "status": 404,
  "message": "No permission found with these filters"
}

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

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

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

URI Parameters

HideShow

name: string (optional) Example: admin
a group name, or part of a group name.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "groups": [
    {
      "id": 3,
      "name": "admin",
      "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": "admin",
  "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/admin/directpermissions

URI Parameters

HideShow

user: string (required) Example: admin
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/admin/allpermissions

URI Parameters

HideShow

user: string (required) Example: admin
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/admin/groups

URI Parameters

HideShow

user: string (required) Example: admin
user being requested.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "groups": [
    {
      "id": 3,
      "name": "group1"
    },
    {
      "id": 4,
      "name": "admin"
    }
  ]
}

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

Auth ¶

Session management ¶

Create sessionPOST/

Example URI

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Known users manipulation ¶

List known usersGET/user

Example URI

Headers

Headers

Body

Headers

Body

Register a new userPOST/user

Example URI

Headers

Body

Headers

Body

Headers

Body

Individual user settings ¶

Get user infoGET/user/

Example URI

Headers

Headers

Body

Headers

Body

Headers

Body

Update user infoPUT/user/

Example URI

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Remove userDELETE/user/

Example URI

Headers

Headers

Body

Headers

Body

Headers

Body

List tenant services ¶

List tenantsGET/admin/tenants

Example URI

Headers

Body

CRUD Permissions and Group ¶

Permissions creation and search ¶

Create a new permissionPOST/pap/permission

Example URI

Headers

Body

Headers

Body

Search permissionGET/pap/permission?{path,method,permission}

Example URI

Headers

Headers

Body

Headers

Create session
POST`/`

List known users
GET`/user`

Register a new user
POST`/user`

Get user info
GET`/user/`

Update user info
PUT`/user/`

Remove user
DELETE`/user/`

List tenants
GET`/admin/tenants`

Create a new permission
POST`/pap/permission`

Search permission
GET`/pap/permission?{path,method,permission}`

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

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

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

Create a new group
POST`/pap/group`

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

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

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

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

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