Authorization

API Authorization calls

The authorization controller is used to login to the API, in addition user management.

When a login call is completed, the API will return a bearer token which should be used in the auth header of all future calls. This token is set to expire 10 minutes after its generation.

A refresh token is also included in the login response, and this is used in the body of the refresh call to get new tokens with refreshed expiry times. Ensure a refresh call is made prior to any given bearer token's expiry to avoid having to login again.

Login to engine API

post

Body

Engine API Login credentials

usernamestringRequired

Username

passwordstringRequired

Password

Responses

200

Ok response

application/json

401

Unauthorized

application/json

500

Internal Server Error

application/json

post

HTTPcURLJavaScriptPython

POST /api/v1/auth/login HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 55

{
  "username": "exampleUser",
  "password": "examplePassword"
}

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiIyYTZlMzQzNC1kZjI4LTQ1NDQtOTYzYS1mZTViMmQ1NTg0ZWIiLCJyb2xlcyI6MjU1LCJpYXQiOjE2NzMyODY1MjYsImV4cCI6MTY3MzI5MDEyNn0.eDnLoBQSp8mkI6C4rkgm1iBFL_dSPAWoYiXOtitaCAs",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiIyYTZlMzQzNC1kZjI4LTQ1NDQtOTYzYS1mZTViMmQ1NTg0ZWIiLCJyZWZyZXNoVG9rZW4iOnRydWUsImlhdCI6MTY3MzI4NjUyNiwiZXhwIjoxNjczMzI5NzI2fQ.TsB2JUhjh8I8dvJrXxVNL4anJKUO5j_sS2EL3x4c5SE"
}

Refresh API tokens

post

Body

Refresh token data

refreshTokenstringRequired

Refresh token

Responses

200

Ok response

application/json

401

Unauthorized

application/json

500

Internal Server Error

application/json

post

HTTPcURLJavaScriptPython

POST /api/v1/auth/refresh HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 234

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiIyYTZlMzQzNC1kZjI4LTQ1NDQtOTYzYS1mZTViMmQ1NTg0ZWIiLCJyZWZyZXNoVG9rZW4iOnRydWUsImlhdCI6MTY3MTYxNzY2MiwiZXhwIjoxNjcxNjYwODYyfQ.Mwjbo13AQH-wyfuK_HI5sjwikUZSRboyHa6nkrkm-Xg"
}

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiIyYTZlMzQzNC1kZjI4LTQ1NDQtOTYzYS1mZTViMmQ1NTg0ZWIiLCJyb2xlcyI6MjU1LCJpYXQiOjE2NzMyODcyMDUsImV4cCI6MTY3MzI5MDgwNX0.T2D6l1AMMEbBJXshJjyyHjt1t7XUB5k35Vegusg2HZc",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiIyYTZlMzQzNC1kZjI4LTQ1NDQtOTYzYS1mZTViMmQ1NTg0ZWIiLCJyZWZyZXNoVG9rZW4iOnRydWUsImlhdCI6MTY3MzI4NzIwNSwiZXhwIjoxNjczMzMwNDA1fQ.AJxGVcUr0raGWYYUDY8hxq9It_gd7byodocjKuzo35I"
}

Add a new user

post

Body

New user data

usernamestringRequired

Username

passwordstring · min: 8Required

Password

Responses

200

Ok response

application/json

401

Unauthorized

application/json

500

Internal Server Error

application/json

post

HTTPcURLJavaScriptPython

POST /api/v1/auth/user HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 147

{
  "username": "[email protected]",
  "password": "12345678",
  "roles": {
    "admin": false,
    "flows": true,
    "configure": false,
    "subscribe": true,
    "write": true,
    "read": true
  }
}

{
  "_id": "71abe4f9-c636-4b1c-950f-968459cea908"
}

Get user ID

get

Path parameters

usernamestringRequired

Username

Responses

200

Ok response

application/json

401

Unauthorized

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

get

HTTPcURLJavaScriptPython

GET /api/v1/auth/user/{username} HTTP/1.1
Host: 
Accept: */*

71abe4f9-c636-4b1c-950f-968459cea908

Get all users

get

Responses

200

Ok response

application/json

Responsestring[]

Ok response

Example: ["admin","[email protected]","[email protected]"]

401

Unauthorized

application/json

500

Internal Server Error

application/json

get

HTTPcURLJavaScriptPython

GET /api/v1/auth/users HTTP/1.1
Host: 
Accept: */*

[
  "admin",
  "[email protected]",
  "[email protected]"
]

Get user roles

get

Path parameters

_idstringRequired

User ID

Responses

200

Role profile

application/json

401

Unauthorized

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

get

HTTPcURLJavaScriptPython

GET /api/v1/auth/user/roles/{_id} HTTP/1.1
Host: 
Accept: */*

{
  "admin": false,
  "flows": true,
  "configure": false,
  "subscribe": true,
  "write": true,
  "read": true
}

Set user roles

patch

Path parameters

_idstringRequired

User ID

Body

New roles information

Responses

200

Ok response

application/json

401

Unauthorized

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

patch

HTTPcURLJavaScriptPython

PATCH /api/v1/auth/user/roles/{_id} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 97

{
  "roles": {
    "admin": true,
    "flows": true,
    "configure": false,
    "subscribe": true,
    "write": true,
    "read": true
  }
}

{
  "roles": {
    "admin": true,
    "flows": true,
    "configure": false,
    "subscribe": true,
    "write": true,
    "read": true
  }
}

Set user password

patch

Path parameters

_idstringRequired

User ID

Body

New password information

passwordstring · min: 8Required

New password

Responses

200

Ok response

application/json

401

Unauthorized

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

patch

HTTPcURLJavaScriptPython

PATCH /api/v1/auth/user/password/{_id} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 19

{
  "password": "text"
}

{
  "result": "text"
}

Delete a user

delete

Path parameters

_idstringRequired

Responses

200

Default Response

application/json

401

Unauthorized

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

delete

HTTPcURLJavaScriptPython

DELETE /api/v1/auth/user/{_id} HTTP/1.1
Host: 
Accept: */*

{
  "result": "OK"
}