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

Body

application/json

Engine API Login credentials

username*string

Username

password*string

Password

Response

200401500

Ok response

Body

*/*

token*string

API token

refreshToken*string

API refresh token

tokenLifetime*number

API token lifetime in seconds

refreshTokenLifetime*number

API refresh token lifetime in seconds

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/auth/login', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "username": "exampleUser",
      "password": "examplePassword"
    }),
});
const data = await response.json();

Response

200401500

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

Refresh API tokens

POST/api/v1/auth/refresh

Body

application/json

Refresh token data

refreshToken*string

Refresh token

Response

200401500

Ok response

Body

*/*

token*string

API token

refreshToken*string

API refresh token

tokenLifetime*number

API token lifetime in seconds

refreshTokenLifetime*number

API refresh token lifetime in seconds

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/auth/refresh', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiIyYTZlMzQzNC1kZjI4LTQ1NDQtOTYzYS1mZTViMmQ1NTg0ZWIiLCJyZWZyZXNoVG9rZW4iOnRydWUsImlhdCI6MTY3MTYxNzY2MiwiZXhwIjoxNjcxNjYwODYyfQ.Mwjbo13AQH-wyfuK_HI5sjwikUZSRboyHa6nkrkm-Xg"
    }),
});
const data = await response.json();

Response

200401500

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

Add a new user

POST/api/v1/auth/user

Body

application/json

New user data

username*string

Username

password*string

Password

roles*object

Role profile

Response

200401500

Ok response

Body

*/*

_id*string

User ID

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/auth/user', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "username": "[e-mail]",
      "password": "12345678",
      "roles": {
        "admin": false,
        "flows": true,
        "configure": false,
        "subscribe": true,
        "write": true,
        "read": true
      }
    }),
});
const data = await response.json();

Response

200401500

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

Get user ID

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

Path parameters

username*string

Username

Response

200401404500

Ok response

Body

*/*

_id*string

User ID

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/auth/user/{username}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200401404500

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

Get all users

GET/api/v1/auth/users

Response

200401500

Ok response

Body

*/*

itemsstring

Username

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/auth/users', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200401500

[
  "admin",
  "[e-mail]",
  "[e-mail]"
]

Get user roles

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

Path parameters

_id*string

User ID

Response

200401404500

Role profile

Body

*/*

admin*boolean

Has admin permission

flows*boolean

Has flows editing permission

configure*boolean

Has configuration editing permission

subscribe*boolean

Has subscription permission

write*boolean

Has write permission

read*boolean

Has read permission

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/auth/user/roles/{_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200401404500

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

Set user roles

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

Path parameters

_id*string

User ID

Body

application/json

New roles information

roles*object

Role profile

Response

200401404500

Ok response

Body

*/*

roles*object

Role profile

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/auth/user/roles/{_id}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "roles": {
        "admin": true,
        "flows": true,
        "configure": false,
        "subscribe": true,
        "write": true,
        "read": true
      }
    }),
});
const data = await response.json();

Response

200401404500

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

Set user password

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

Path parameters

_id*string

User ID

Body

application/json

New password information

password*string

New password

Response

200401404500

Ok response

Body

*/*

result*string

Result

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/auth/user/password/{_id}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "password": "text"
    }),
});
const data = await response.json();

Response

200401404500

{
  "result": "text"
}

Delete a user

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

Path parameters

_id*string

Response

200401404500

Default Response

Body

*/*

result*string

Result

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/auth/user/{_id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

200401404500

{
  "result": "OK"
}