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

401

Unauthorized

application/json

500

Internal Server Error

application/json

post

/api/v1/auth/login

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

application/json

Refresh token data

refreshTokenstringRequired

Refresh token

Responses

200

Ok response

application/json

401

Unauthorized

application/json

500

Internal Server Error

application/json

post

/api/v1/auth/refresh

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

application/json

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

/api/v1/auth/user

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

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

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

401

Unauthorized

application/json

500

Internal Server Error

application/json

get

/api/v1/auth/users

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

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

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

application/json

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

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

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

application/json

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

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

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

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

HTTPcURLJavaScriptPython

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

{
  "result": "OK"
}