Authorization (auth) Endpoint

Used to log in to Devii, and get Query endpoints and JWT tokens which are used to connect to the API with external software.

Connect to endpoint

Send a POST request to the endpoint https://api.devii.io/auth, either as form data or as application/json, with the following fields: login, password, and tenantid. The login and password will be the credentials for your Devii portal account; the tenantid will be the ID you got from the Database card.

const AUTH_URL = "https://api.devii.io/auth";

Show Code

JS Fetch

const AUTH_URL = "https://api.devii.io/auth";

var formdata = new FormData();
formdata.append("login", "demo_user");
formdata.append("password", "demouser");
formdata.append("tenantid", "179");

var requestOptions = {
  method: "POST",
  body: formdata,
  redirect: "follow",
};

fetch(AUTH_URL, requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Axios Client

import axios from "axios";

//https://axios-http.com/docs/intro

try {
  // Login to Devii
  const config = {
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
    },
  };

  const AUTH_URL = "https://api.devii.io/auth";

  const params = new URLSearchParams();
  params.append("login", "demo_user");
  params.append("password", "demo_password");
  params.append("tenantid", "1111");

  const result = await axios.post(AUTH_URL, params, config);
  console.log(result);

  const access_token = result.data.access_token;
  const query_endpoint = result.data.routes.query;
  const role_pbac_endpoint = result.data.routes.roles_pbac;
} catch (e) {
  console.log(e);
  return;
}

Successful Response

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzUxMiJ9...",
    "message": "Logged in as demo_user.",
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzUxMiJ9...",
    "roleid": 1611,
    "routes": {
        "base": "https://api.devii.io/",
        "query": "https://api.devii.io/query",
        "roles_pbac": "https://api.devii.io/roles_pbac"
    },
    {Truncated Schema...}
}

The response will contain a JSON object with a lot of data. The token needed to connect to the API endpoints is under the field "access_token". It's a JSON Web Token, cryptographically signed by the Devii server, which indicates your role (user) and tenant IDs.

There is also a JWT in the field "refresh_token", which can be used to request a new access token from the /auth endpoint (more on that later); a "routes" field which gives the URL routes to your tenant's endpoints; "roleid" which gives your currently logged in role ID; and two fields called "schema" and "rpb_schema", which give full JSON GraphQL schema data for the query and roles_pbac (control) schemas of your tenant, respectively. To gain access now, what you'll need is the "access_token" and the "routes" fields.

Troubleshooting

Not authorized

{ "error": "Invalid credentials.", "status": 403 }

{ "error": "Role is not in this tenant.", "status": 400 }

{ "error": "No such role admin for tenant 14.", "status": 404 }

{ "error": "Non-administrators may not access other roles.", "status": 400 }

{
  "error": "Unauthorized access: Missing Authorization Header",
  "status": 401
}

Password Security

{ "error": "New password must be different from old password.", "status": 400 }