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

application/json

Engine API Login credentials

usernamestringRequired

Username

passwordstringRequired

Password

Responses

200

Ok response

application/json

Ok response

tokenstringRequired

API token

refreshTokenstringRequired

API refresh token

tokenLifetimenumberRequired

API token lifetime in seconds

refreshTokenLifetimenumberRequired

API refresh token lifetime in seconds

401

Unauthorized

application/json

500

Internal Server Error

application/json

post

/api/v1/auth/login

HTTPcURLJavaScriptPython

POST /api/v1/auth/login HTTP/1.1
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

application/json

Refresh token data

refreshTokenstringRequired

Refresh token

Responses

200

Ok response

application/json

Ok response

tokenstringRequired

API token

refreshTokenstringRequired

API refresh token

tokenLifetimenumberRequired

API token lifetime in seconds

refreshTokenLifetimenumberRequired

API refresh token lifetime in seconds

401

Unauthorized

application/json

500

Internal Server Error

application/json

post

/api/v1/auth/refresh

HTTPcURLJavaScriptPython

POST /api/v1/auth/refresh HTTP/1.1
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

application/json

New user data

usernamestringRequired

Username

passwordstring · min: 8Required

Password

Responses

200

Ok response

application/json

Ok response

_idstringRequired

User ID

401

Unauthorized

application/json

500

Internal Server Error

application/json

post

/api/v1/auth/user

HTTPcURLJavaScriptPython

POST /api/v1/auth/user HTTP/1.1
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

Ok response

_idstringRequired

User ID

401

Unauthorized

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

get

/api/v1/auth/user/{username}

HTTPcURLJavaScriptPython

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

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

Get all users

get

Responses

200

Ok response

application/json

string[]Optional

Ok response

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

401

Unauthorized

application/json

500

Internal Server Error

application/json

get

/api/v1/auth/users

HTTPcURLJavaScriptPython

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

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

Get user roles

get

Path parameters

_idstringRequired

User ID

Responses

200

Role profile

application/json

Role profile

adminbooleanRequired

Has admin permission

flowsbooleanRequired

Has flows editing permission

configurebooleanRequired

Has configuration editing permission

subscribebooleanRequired

Has subscription permission

writebooleanRequired

Has write permission

readbooleanRequired

Has read permission

401

Unauthorized

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

get

/api/v1/auth/user/roles/{_id}

HTTPcURLJavaScriptPython

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

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

Set user roles

patch

Path parameters

_idstringRequired

User ID

Body

application/json

New roles information

Responses

200

Ok response

application/json

Ok response

401

Unauthorized

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

patch

/api/v1/auth/user/roles/{_id}

HTTPcURLJavaScriptPython

PATCH /api/v1/auth/user/roles/{_id} HTTP/1.1
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

application/json

New password information

passwordstring · min: 8Required

New password

Responses

200

Ok response

application/json

Ok response

resultstringRequired

Result

401

Unauthorized

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

patch

/api/v1/auth/user/password/{_id}

HTTPcURLJavaScriptPython

PATCH /api/v1/auth/user/password/{_id} HTTP/1.1
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

resultstringRequired

Result

401

Unauthorized

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

delete

/api/v1/auth/user/{_id}

HTTPcURLJavaScriptPython

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

{
  "result": "OK"
}