Skip to main content

API Tokens

Distributor steps for creating API Tokens on an Application in Encompass so API Commands run without a logged-in user, plus token security tips. Needs API Edit and API Solution Admin permissions.

B
Written by Bailey Naas-Thornton

Minimum Version Required: 22.01

Pre-Conditions

  • User must have API Edit and API Solution Admin permission to be able to view, create, and edit API Tokens.

Steps

When an API request is made to Encompass, the request must either being from an actively logged in user, or it must include an active API Token in the request body.

API Tokens are what allows your API Commands to be accessible without being actively logged into the system.

If an actively logged in user accesses a URL with an API Token on it, the API Token will be ignored, the user's session will take preference over the API Token.

To create an API Token (requires API Solution Admin permission):

  1. Go to your Application on the Applications table, the same Application with the API Commands that the token will be used on.
    ​
    ​

  2. Click Sub-Tables -> API Tokens
    ​
    ​

  3. Click the 'Add API Tokens' button
    ​
    ​

  4. For the Permission Code Arr value, you will need to enter a delimited list of permissions that this API Token should have, separated by the ! (exclamation) character

Example PermissionCodeArr:

Everyone!IsEmployee!TableImport!FusionView!CustomerView

Best Practices

  • API Tokens must be kept secret, they should be treated the same as a username/password combination
    ​
    ​

  • Periodically rotate your API Tokens by creating a new one, replacing it in your application/code, and then deactivating the old one
    ​
    ​

  • If an API Token is suspected to be compromised, replace it with a new one
    ​
    ​

  • API Tokens should be sent in the HTTP request body for improved security
    ​
    ​

  • Do not grant your API Token more permission codes than are necessary

Did this answer your question?