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