API Keys and Key Permissions (v2)

In the EVRYTHNG Platform there are two mechanisms governing how different actors (users - through operator accesses, and machines or services - through access tokens) can interact with resources. These are called permissions - that define a role - and conditions. In broad terms, permissions determine what type of resources an actor can see or modify while conditions determine what particular resources an actor can see or modify.
See Roles and Permissions to learn more about roles and Restrictive Conditions to understand how conditions work.

Each time a REST call is made to the API, the Platform checks that the API key exists, and that that key's permissions allow that call to be made. If this security check does not pass the response will be 403 Forbidden.

The API key is also used to define the resources the actor is restricted to - i.e.: permissions authorised the caller to interact with factories but conditions restricted the actor to only factory 1 and factory 2. Depending on the API key used, the platform determines the account you are permitted to see, and if applicable, the resources scoped to that account.


Key Types

Operator API Key

An Operator API Key represents an owner or collaborator on an account, and is generated when an Operator creates a new account. An Operator collaborating on several accounts will get a new Operator API Key for each one. This key can be regenerated at any time through the Dashboard in the 'Account Settings' section if it is compromised.

❗️

Important

The Operator API Key gives the most access to your account (including all resources) and therefore must be kept secret, and never used in publically accessible code, to prevent any abuse or data theft.

Access Token

An access token represents an anonymous user or service that is allowed to access the platform on a given account. This token is generated when an authorised Operator creates one through the Access Tokens API and assigns roles and conditions to control the token access. It is the secret counterpart key designed to be used only by back-end applications whose code is not exposed e.g: Ruby, PHP, Java or Node apps when they require additional permissions to create or modify resources. Like the Operator API Key, this key should not be used in client side applications (e.g: JavaScript web apps).

Read more about Access Tokens and Operator Access to learn how to manage these keys.

Updated 6 months ago

API Keys and Key Permissions (v2)


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.