📘

This guide assumes knowledge of access levels, tags, and service accounts. To learn more about these concepts, see Getting Started: Setting up your Formant organization.

In the case where you are embedding a Formant view in an external UI, you can use the Login embed method of the Auth endpoint to set the appropriate access level for a session, without having to create Formant users.

This guide will teach you how to generate an authorization token with the Login embed method of the Auth endpoint, using the tags parameter to set the appropriate access level.

Prerequisites

Create a service account

You'll need to create a service account to authenticate your Formant session. For more information, see Create a service account.

📘

When creating your service account, consider the permissions you want to grant to the end user. You will control permissions by assigning a role to your service account.

A viewer role will have view-only access.

An operator role will be allowed to view data, send commands, and teleoperate the device (if your view is designed to issue commands or teleoperate your device).

For more information, see Users, roles, and teams .

Tag your service account (optional)

If you want to restrict the access level of your service account, apply tags to the service account. This tag set will be joined with the tag sets provided with the tags parameter when determining access levels before generating the authorization token.

For example, if your service account has the tag site: albuquerque, and in the tags parameter you pass the tag manufacturer: acme, the tag set for that session will be: site: albuquerque, manufacturer: acme.

For more information, see Configure access levels.

Step 1: Generate auth token with restricted access

Call the Login embed method of the Auth endpoint with your service account credentials and tags:

import requests

url = "https://api.formant.io/v1/admin/auth/login-embed"

payload = {
    "email": "SERVICE_ACCOUNT_EMAIL",
    "password": "SERVICE_ACCOUNT_PASSWORD",
    "tokenExpirationSeconds": 86400,
    "scope": { "tags": {} },
    "roleId": "abc123"
}
headers = {
    "accept": "application/json",
    "content-type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
     --url https://api.formant.io/v1/admin/auth/login-embed \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "email": "SERVICE_ACCOUNT_EMAIL",
  "password": "SERVICE_ACCOUNT_PASSWORD",
  "tokenExpirationSeconds": 86400,
  "scope": {
    "tags": {}
  }
}
'

scope parameter syntax

You can use the scope parameter to set uniform access to all resources. You can also set specific access levels to specific resources.

The overall syntax for a scope object looks like this:

{
  "scope": {
    "tags": {
      "site": ["albquerque"]
    },
    "devices": {
      "manufacturer": ["acme", "roadrunner"] 
    },
    "events": {
      "user": ["wile-e-coyote"]
    }
  }
}

The tags parameter restricts access to all resources to users whose tag set is equal to or a subset of the provided tag set.

If specified, devices and events will override the tag set defined by tags for that particular resource. In the above code block:

• The tag set site: albuquerque is applied to all resources.
• For devices access, tags is overridden with the tag set (manufacturer: acme OR manufacturer: roadrunner).
• For events access, tags is overridden with the tag set user: wile-e-coyote.

The following sections describe the access behavior of various tag sets in more detail.

📘

Each example uses the tags parameter for syntax reference. The same syntax is valid for the devices and events parameters as well.

Unrestricted access and no access

Single tag behavior

The simplest tag set key: value has the following syntax:

{ 
  "scope": 
    "tags": {
      "key": ["value"] 
    }
  }
}

For example, to access all resources with the tag fruit: cherry, your scope would be:

{
  "scope": {
    "tags": { 
      "fruit": ["cherry"] 
    }  
  }
}

Single key, multiple values

To access resources with multiple values for a given key, you can provide the values in an array:

{ 
  "scope": {
    "tags": { 
      "key": ["value-1", "value-2"] 
    }    
  }  
}

Such as:

{ 
  "scope": {
    "tags": { 
      "fruit": ["cherry", "plum"] 
    } 
  } 
}

This example would give access to all devices tagged with either fruit: cherry OR fruit: plum.

Multiple keys, single value

To access resources with a set of tags, you can supply multiple keys:

{ 
  "scope":
    "tags": { 
      "key-1": ["value-1"], 
      "key-2": ["value-2"] 
    } 
  }
}

Such as:

{ 
  "scope": {
    "tags": { 
      "fruit": ["cherry"], 
      "color": ["black"] 
    } 
  } 
}

This example would give access to all devices which have both fruit: cherry AND color:black tags applied.

Multiple keys, multiple values

You can access entities with a set of tags.
keys, each of which has a range of values:

{ 
  "scope":
    "tags": { 
      "key-1": ["value-1","value-2"], 
      "key-2": ["value-3"] 
    } 
  } 
}

Such as:

{ 
  "scope":
    "tags": { 
      "fruit": ["cherry", "blackberry"], 
      "color": ["black"] 
    } 
  } 
}

This example would give access to all devices with (fruit: cherry AND color: black) OR (fruit: blackberry AND color: black).

Step 2: Refresh your auth token

The auth token is a JWT token. You can use JWT decoding tools to see when the token expires. You can refresh it at any time by following Step 1 again.

See also

• Embedded views
• Embed a Formant view in an external site
• Configure access levels
• Create a service account
• Users, roles, and teams

👋

If you notice an issue with this page or need help, please reach out to us! Use the 'Did this page help you?' buttons below, or get in contact with our Customer Success team via the Intercom messenger in the bottom-right corner of this page, or at [email protected].