Instance API Tokens

Instance tokens allow you to interact with a single Losant Instance at a scope level you define. Using an instance token, users can create, read, update, or delete organization objects and other instance resources.

Note that instance tokens can not be used to modify child resources of organizations (applications, dashboards, devices, etc.).

Viewing Instance Tokens

You can view the API tokens for your instance by choosing API Tokens in the subnavigation of the Losant Instance Manager.

The list of instance tokens includes the token’s name, description, its creator (which may be yourself or another API token), and the token’s expiration date.

Generating an API Token

Instance API tokens can be added to your instance by using the Add Instance Token button on the API Tokens page. Token setup requires four pieces of information:

Name and Description

The token’s name is required. It is simply for display purposes and is required to help you differentiate your instance tokens. The token’s name in no way affects its functionality. Optionally, a longer description may be provided for additional information on the token.

Token Expiration Date

By default, the ”Never expires” option is selected. This means that by default the token will never expire. Optionally, if you would like the instance token to expire, choose ”Expires at …” and then set a future date/time after which requests using this token should no longer be accepted. The default expiration date with this option is one year from creation.

Note: The expiration date cannot be changed after token creation. If the expiration date passes while the token is in use, you will have to generate a new token and replace it within your authentication requests.

Token Permissions

There are three options for setting the token’s scope …

All permissions allows the token to create, read, update, and delete all instance resources (including the instance itself) as well as any additional resources that are added in the future.

Read only allows the token to read – but not modify – all instance sub-resources (including the instance itself) as well as any additional resources that are added in the future.

Custom … allows for selecting specific resource / action combinations from the instance that the token should be allowed to access. Choosing this option reveals a list of all instance-specific API calls in the Losant Platform, each of which may be individually added to the token’s scope.

The checkboxes next to the resource names will automatically check or uncheck all actions under that resource. However, checking such a box does not provide the token access to any new actions that may be added under that resource in the future. If a new action is added under a resource, and you would like your token to have access to that action, you will have to generate a new token.

Note that a token’s scope cannot be changed after token creation. If you find you need additional permissions not allowed by the token, you will have to create a new token. Likewise, if you would like to revoke permissions originally supplied to a token, you will have to delete the token and create a new one with the desired scope.

Getting the Token

After clicking Create Instance Token, the newly created token will be displayed. You will either need to copy it to a secure location or download it to a file on your computer.

IMPORTANT: Losant does not store API tokens and they cannot be recovered or regenerated if lost. If you fail to save your token before closing the modal, you will have to generate a new instance API token.

When you’re finished, check the I have copied my instance token to a safe place. box and click Close Window.

Deleting / Deactivating an API Token

To temporarily deactivate an instance API token …

• Toggle the switch in the list view, OR
• From the token’s detail page, select the “Inactive” radio button under the “Status” label and save the token.

If a token has expired, is no longer needed, or is thought to have been compromised, you may permanently delete it by:

• Clicking on the Delete icon in the token list, OR
• Clicking the Delete Instance Token button on the token’s detail page

Using API Tokens

To learn more about using API tokens with our REST API, check out the various Losant REST client libraries.