Skip to main content

Query (roles_pbac) Endpoint

Used to make requests to the control API that controls your tenant's roles, classes, and policy (among other things). Standard GraphQL endpoint that take the usual fields "query", "variables", and "operationName".

For all requests send to the endpoints in "routes", set an HTTP "Authorization" header to the text "Bearer " and then the contents of the "access_token" field. This token will be checked by the Devii server, and its cryptographic signature means it can't be changed without being invalidated, and can't be faked. It will positively identfiy the logged in role as being authorized.

The access token is not permanent: it has a default expiration time of 1 day (86400 seconds).

The refresh token can be used to request a new access token, by sending a GET request to the /auth endpoint with the Authorization header set to "Bearer [refresh_token]". This will issue a new access token and resend the other data. The refresh token has a default expiration time of 7 days (604800 seconds).

Auth Endpoint 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...}
}

Example​

{
  role {
    roleid
    name
  }
}
Show Code
const ROLES_PBAC = "https://api.devii.io/roles_pbac";
const ACCESS_TOKEN = auth_response.access_token;
const ROLES_PBAC = auth_response.routes.roles_pbac;
const query = "{\r\n  role {\r\n    roleid\r\n    name\r\n  }\r\n}";

var myHeaders = new Headers();
myHeaders.append("Authorization", `Bearer ${ACCESS_TOKEN}`);
myHeaders.append("Content-Type", "application/json");

var graphql = JSON.stringify({
  query: query,
  variables: {},
});
var requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: graphql,
  redirect: "follow",
};

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

Password Strength and Token Expiration​

The tenant_auth_policy table is used for password validation, and for setting the expiration times of JWT authentication tokens.

mutation ($tenant_auth_policyInput: tenant_auth_policyInput) {
  update_tenant_auth_policy(input: $tenant_auth_policyInput) {
    length
    uppercase
    numbers
    special
    nonletters
    strength
    access_expiration
    refresh_expiration
  }
}
Variables
{
  "tenant_auth_policyInput": {
    "length": 8,
    "uppercase": 1,
    "numbers": 1,
    "special": 1,
    "nonletters": 1,
    "strength": 0.5,
    "access_expiration": 86400,
    "refresh_expiration": 604800
  }
}

Utility functions​

These functions are designed to perform miscellaneous operations that are not easily represented by simple object queries and mutations, providing introspection and role control as well as statistical and schema insights into your tenant.

introspect​

GenericScalar

Reintrospect and reload the database schema. Returns the new schema JSON.

Show Example Query
{
  Utility {
    introspect
  }
}

available_schemas_and_tables​

GenericScalar

Returns a JSON object with keys being the available schemas in the tenant database, values being lists of tables in each schema. For database platforms that do not support multiple schemas, the single key will be the name of the database. This data is for use in configuring schema and table whitelisting.

Show Example Query
{
  Utility {
    available_schemas_and_tables
  }
}

Output:

{
  "data": {
    "Utility": {
      "available_schemas_and_tables": {
        "demo_test1": ["user"]
      }
    }
  }
}

tenant_statistics​

( startdate Date, enddate Date ) [tenant_statistics]

Returns the following statistics for the tenant:total database storage used, total file storage used, number of logins, numberof API calls, and processing hours used within the given date range. If the date range is not set, startdate will default to the beginning of the current calendar month, and enddate will default to the current date.

Show Example Query
{
  Utility {
    tenant_statistics(startdate: "2023-01-18", enddate: "2023-01-24") {
      entryid
      fordate
      created
      requests
      proctime
      newroles
      activerolecount
      logins
      database_bytes
      files_bytes
    }
  }
}

Output:

{
  "data": {
    "Utility": {
      "tenant_statistics": [
        {
          "activerolecount": 6,
          "created": "2023-01-19T00:08:06.568744",
          "database_bytes": 10158883,
          "entryid": "289",
          "files_bytes": 1653207,
          "fordate": "2023-01-18",
          "logins": 10,
          "newroles": 0,
          "proctime": "4:27:15.433202",
          "requests": 378
        }
      ]
    }
  }
}

anonymous_logins​

( enable Boolean ) GenericScalar

Set or get the status of anonymous logins on the tenant. Anonymous logins enable access to the tenant without a defined role, thus requiring no authentication. This feature is accessed at the /anonauth server endpoint. The primary use case is for self-registration of new users for a tenant's apps, and thus creation of new roles. Access to public data is another use case.

Anonymous logins are supported by means of a 'Nobody' role, which is created for the tenant the first time they are enabled. This Nobody role will have normal capabilities, as well as the ability to create new roles. Policy will be added to enable the Nobody role to view all normal roles in the tenant, but the tenant root role will need to add policy to give it access to tables in the tenant schema, other than those with global access. Be cautious with this: tables with anonymous access enabled means anyone could query or mutate them as permitted!

If a tenant has anonymous logins enabled, and they are then disabled, the Nobody role will be flagged as deleted, thus blocking use of /anonauth for the tenant. If later re-enabled, the existing Nobody role's deleted flag will be cleared.

With "enable" set to True, enables anonymous logins; set to False, disables them. Returns the roleid of the configured Nobody role if enabled, False otherwise.

Show Example Queries

Enable

{
  Utility {
    anonymous_logins(enable: true)
  }
}

Output

{
  "data": {
    "Utility": {
      "anonymous_logins": 1111
    }
  }
}

Disable

{
  Utility {
    anonymous_logins(enable: false)
  }
}

Output

{
  "data": {
    "Utility": {
      "anonymous_logins": false
    }
  }
}

Check if is enabled or disabled

{
  Utility {
    anonymous_logins
  }
}

Output:

{
  "data": {
    "Utility": {
      "anonymous_logins": false
    }
  }
}

role_token​

( roleid Int! ) String

Returns a refresh token for the role identified by ROLEID. Non-administrators may only access roles which they created.

Show Example Query
{
  Utility {
    role_token(roleid: 1609)
  }
}

Output:

{
  "data": {
    "Utility": {
      "role_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzUxMiJ9..."
    }
  }
}

check_connection​

( driver String!, host String!, database String!, username String!, password String! ) Boolean

Returns true if the system can connect to the database server indicated by the parameters. Otherwise, an error is signalled. At no point are the parameters saved in any log or database; they are only used for connection testing. Connections are tested by sending a 'SELECT 1;' statement to the server.

Show Example Query
{
  Utility {
    check_connection(
      driver: "mysql"
      host: "deviimysql.mysql.database.azure.com"
      database: "demo_test1"
      username: "demo_user"
      password: "demo1234"
    )
  }
}

Output:

{
  "data": {
    "Utility": {
      "check_connection": true
    }
  }
}

Troubleshooting​