API Keys and Key Permissions (legacy)

In the EVRYTHNG Platform there are two mechanisms governing how different actors (apps, users, devices, etc.) can interact with resources. These are called permissions and scopes. In broad terms, permissions determine what an actor can modify while scopes determine what an actor can see.

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. See below for more information about the permissions of each type of API key.

The API key is also used to define the scope of the request - i.e.: what the caller is authorized to see and interact with. Depending on the API key used, the platform determines the account you are permitted to see, and if applicable, which projects within that account, and the resources scoped to those projects.

In the case of an Application User API key, the scope is restricted to what that particular user is permitted to see or interact with. Consider scope as a filter applied to account resources. If you try to access a resource not in your scope it will not be visible, and the response will be 404 Not Found.

Read Scoping to learn more about using scopes with the API.

---

Types of Scope

There are three main types of scope that can be used to limit or assign access and visibility of resources. The scope of any given resources will be set or can be changed by the API key used to create or modify it. These are summarised in the sections below.

Account Scope

Each API key is associated at a high level with a single Dashboard Account. Resources (Thngs, products, etc.) created with an API key are therefore created within, and scoped to, the corresponding account. Other API keys associated with the same account will also be able to see those resources if they have the correct scope and permissions.

Resources always belong to exactly one account and can not be transferred from one account to another.

Project Scope

All resources created by applications or Application Users within a project are automatically scoped to that project, and visible only to actors belonging to that project. In addition, and other resources that exist outside that project may be scoped to include it by updating the scopes.projects field. Resources can be scoped to more than one project to be shared between them.

The project scope of a resource is set upon creation based any project-scoping of the request, such as using the project query parameter, or using an Application User API Key belonging to that project. Resources created without a project-scoped request are not visible to any project-scoped actor, with the exception of an account Operator.

📘

Note

By definition Application API keys and Application User keys are already scoped to a specific project. This behaviour can not be overridden as it enforces the boundaries of projects.

User Scope

The Application User API keys also defines a user scope. All resources created by an Application User exist in scope of the user and the project that users belongs to. As in the case of the project scope, the user scope of resources can be updated afterwards through a PUT request on the resource to update the scopes.users field.

The initial value of a resource's user scope depends on the scope used for the creation request (such as an Application User API Key), and this value can be overridden using the ?userScope query parameter. This parameter also supports the special values all and me. By default, if a project scope is defined the created resource has the all users scope.

---

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.

Application API Key

The Application API Key is created on a per-application basis. Its access is restricted to mostly read operations and is intended to be used to setup a mobile/web app, as well as to create and identify its Application Users. Its typical use is within a client app and hence can safely be visible in code. This key is not a secret but an additional application identifier with basic read permissions.

Trusted Application API Key

The Trusted Application API Key belongs to each application and can only be read by an account Operator in the Dashboard or through the API. It is the secret counterpart key 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).

Application User API Key

The Application User API Key is generated after Application User authentication (either when creating a new Application User or logging an existing one in), and grants extra privileges to create, own, and modify resources. This is the key to use when interacting with resources belonging to the user, or creating actions representing their activity.

This key is a secret generated at runtime and should not be hard-coded in client side code (e.g., web app JavaScript), since it will expire if the user is logged out, and be regenerated when they log back in.

Device API Key

The Device API Key is generated for a specific existing Thng and grants privileges to update the state of that Thng resource only. Each device that wishes to modify itself (including Thng properties and actions) must generate and use a new Device API Key.

---

Key Permissions

This section lists all the available endpoints in the EVRYTHNG REST API, detailing which API keys can access each endpoint, and the HTTP methods available.

📘

Key Notation

(O) - Operator API key
(A) - Application API key
(U) - Application User API key
(T) - Trusted Application API key
(D) - Device API key

### REST API

https://api.evrythng.com

• /access

  • GET - Read key access information (O, A, T, U, D)

• /accesses

  • POST - Create a new access (U)
  • GET - Read all accesses (U)

• /accesses/:accessId

  • DELETE - Delete an access (U)

• /accounts

  • GET - Read all accounts (O)

• /accounts/:accountId

  • GET - Read an account (O)
  • PUT - Update an account (O)

• /accounts/:accountId/accesses

  • GET - Read account accesses (O)

• /accounts/:accountId/accesses/:accessId

  • GET - Read an account access (O)
  • PUT - Update an account access (O)

• /accounts/:accountId/domains

  • GET - Read account domains (O)

• /accounts/:accountId/shortDomains

  • GET - Read account short domains (O)

• /actions

  • POST - Create an action type (O, T)
  • GET - Read all action types (O, U, T)

• /actions/:actionType

  • POST - Create an action (O, T, U)
  • GET - Read all actions of a type (O, U, T)
  • PUT - Update an action type (O)
  • DELETE - Delete an action type (O, T)

• /actions/:actionType/:actionId

  • GET - Read an action (O, U, T)
  • DELETE - Delete an action (O)

• /adis/orders

  • POST - Create an ADI Order (O)
  • GET - Read all ADI Orders (O)

• /adis/orders/:adiOrderId

  • GET - Read an ADI Order (O)

• /adis/orders/:adiOrderId/events

  • POST - Create an ADI Order event (O)
  • GET - Read all ADI Order events (O)

• /adis/orders/:adiOrderId/events/:orderEventId

  • GET - Read an ADI Order event (O)

• /applications/me

  • GET - Read self application (T, A)
  • PUT - Update self application (T)

• /auth/all/logout

  • POST - Log an Application User out (U)

• /auth/evrythng

  • POST - Log an Application User in (T, A)

• /auth/evrythng/thngs

  • POST - Create a Device API Key (O, T, U)

• /auth/evrythng/thngs/:thngId

  • GET - Read a Device API Key (O, T, U)
  • DELETE - Delete a Device API Key (O, T, U)

• /auth/evrythng/users

  • POST - Create an Application User (T, A)

• /auth/evrythng/users/:evrythngUser/validate

  • POST - Activate an Application User (T, A)

• /batches

  • POST - Create a batch (O)
  • GET - Read all batches (O)

• /batches/:batchId

  • GET - Read a batch (O)
  • PUT - Update a batch (O)
  • DELETE - Delete a batch (O)

• /batches/:batchId/tasks

  • POST - Create a batch task (O)
  • GET - Read all batch tasks (O)

• /batches/:batchId/tasks/:taskId

  • GET - Read a batch task (O)

• /batches/:batchId/tasks/:taskId/logs

  • GET - Read task error logs (O)

• /collections

  • POST - Create a collection (O, U, T)
  • GET - Read all collections (O, U, T)

• /collections/:collectionId

  • GET - Read a collection (O, U, T)
  • PUT - Update a collection (O, U, T)
  • DELETE - Delete a collection (O, T)

• /collections/:collectionId/actions/:actionType

  • POST - Create a collection action (O, U, T)
  • GET - Read all collection actions (O, U, T)

• /collections/:collectionId/actions/:actionType/:actionId

  • GET - Read a collection action (O, U, T)

• /collections/:collectionId/collections

  • POST - Add collections to a collection (O, U, T)
  • GET - Read all collections in a collection (O, U, T)
  • DELETE - Remove all collections in a collection (O, T)

• /collections/:collectionId/collections/:childCollectionId

  • DELETE - Remove a collection from a collection (O, T)

• /collections/:collectionId/thngs

  • PUT - Add Thngs to a collection (O, U, T)
  • GET - Read all Thngs in a collection (O, U, T)
  • DELETE - Remove all Thngs from a collection (O, T)

• /collections/:collectionId/thngs/:thngId

  • DELETE - Remove a Thng from a collection (O, U, T)

• /files

  • POST - Create a file (O)
  • GET - Read all files (O)

• /files/:fileId

  • GET - Read a file (O)
  • DELETE - Delete a file (O)

• /machineLearning/models

  • GET - Read all model types (O, T)
  • POST - Create a model type (O, T)

• /machineLearning/models/:modelType

  • GET - Read a model type (O, T)
  • PUT - Update a model type (O, T)
  • POST - Create a new model of type (O, T)

• /machineLearning/models/:modelType/:modelId

  • GET - Read a model instance (O, T)

• /machineLearning/models/:modelType/:modelId/datasets

  • GET - Read all training datasets (O, T)
  • POST - Create a Training Dataset (O, T)

• /machineLearning/models/:modelType/:modelId/datasets/:datasetId

  • GET - Read a training dataset (O, T)
  • PUT - Update a training dataset (O, T)

• /machineLearning/models/:modelType/:modelId/deployments

  • GET - Read all deployed models (O, T)
  • POST - Create a new model deployment (O, T)

• /machineLearning/models/:modelType/:modelId/deployments/:deploymentId

  • GET - Read a model deployment (O, T)

• /machineLearning/models/:modelType/:modelId/deployments/:deploymentId/predict

  • POST - Creating a new prediction (O, T)

• /places

  • POST - Create a place (O, T)
  • GET - Read all places (O, T, A, U)

• /places/:placeId

  • GET - Read a place (O, T, A, U)
  • PUT - Update a place (O, T)
  • DELETE - Delete a place (O, T)

• /products

  • POST - Create a product (O, T, U)
  • GET - Read all products (O, T, A, U)

• /products/:productId

  • GET - Read a product (O, T, A, U)
  • PUT - Update a product (O, T, U)
  • DELETE - Delete a product (O, T)

• /products/:productId/actions/:actionType

  • POST - Create a product action (O, T, U)
  • GET - Read all product actions (O, T, U)

• /products/:productId/actions/:actionType/:actionId

  • GET - Read a product action (O, T, U)

• /products/:productId/properties

  • POST - Create/update product properties (O, T, U)
  • GET - Read product properties (O, T, A, U)

• /products/:productId/properties/:propertyKey

  • GET - Read a product property (O, T, A, U)
  • PUT - Update a product property (O, T, U)
  • DELETE - Delete a product property (O, T, U)

• /products/:productId/redirector

  • POST - Create a product's redirection (O, T, U)
  • GET - Read a product's redirection (O, T, A, U)
  • PUT - Update a product's redirection (O, T, U)
  • DELETE - Delete a product's redirection (O, T)

• /projects

  • POST - Create a project (O)
  • GET - Read all projects (O)

• /projects/:projectId

  • GET - Read a project (O)
  • PUT - Update a project (O)
  • DELETE - Delete a project (O)

• /projects/:projectId/applications

  • POST - Create an application (O)
  • GET - Read all applications (O)

• /projects/:projectId/applications/:applicationId

  • GET - Read an application (O)
  • PUT - Update an application (O)
  • DELETE - Delete an application (O)

• /projects/:projectId/applications/:applicationId/oauthClients

  • POST - Create an OAuth client (O)
  • GET - Read all OAuth clients (O)

• /projects/:projectId/applications/:applicationId/oauthClients/:clientId

  • GET - Read an OAuth client (O)
  • PUT - Update an OAuth client (O)
  • DELETE - Delete an OAuth client (O)

• /projects/:projectId/applications/:applicationId/reactor/logs

  • GET - Read Reactor logs (O)
  • DELETE - Delete Reactor logs (O)

• /projects/:projectId/applications/:applicationId/reactor/schedules

  • POST - Create a Reactor schedule (O, T)
  • GET - Read all Reactor schedules (O, T)

• /projects/:projectId/applications/:applicationId/reactor/schedules/:scheduleId

  • GET - Read a Reactor schedule (O, T)
  • PUT - Update a Reactor schedule (O, T)
  • DELETE - Delete a Reactor schedule (O, T)

• /projects/:projectId/applications/:applicationId/reactor/script

  • PUT - Update a Reactor script (O)
  • GET - Read a Reactor script (O)

• /projects/:projectId/applications/:applicationId/reactor/script/status

  • GET - Read Reactor script status (O)

• /projects/:projectId/applications/:applicationId/redirector

  • GET - Read an application Redirector (O)
  • PUT - Update an application Redirector (O)

• /projects/:projectId/applications/:applicationId/secretKey

  • GET - Read Trusted App API Key (O)

• /purchaseOrders

  • POST - Create a purchase order (O)
  • GET - Read all purchase orders (O)

• /purchaseOrders/:purchaseOrderId

  • GET - Read a purchase order (O)
  • PUT - Update a purchase order (O)
  • DELETE - Delete a purchase order (O)

• /rateLimits

  • GET - View rate limit information (O, T, A, U, D)

• /redirector

  • GET - Read the account Redirector (O)
  • PUT - Update the account Redirector (O)

• /roles

  • POST - Create an Application User role (O)
  • GET - Read all roles (O, U)

• /roles/:roleId

  • GET - Read a role (O)
  • PUT - Update a role (O)
  • DELETE - Delete a role (O)

• /roles/:roleId/permissions

  • GET - Read an Application User role's permissions (O)
  • PUT - Update role permissions (O)

• /scan/identifications

  • POST - Identify from an image (T, A)
  • GET - Read an identifier (T, A)

• /shipmentNotices

  • POST - Create a shipment notice (O)

• /shipmentNotices/containers

  • POST - Create a shipment notice container (O)

• /shipmentNotices/containers/:containerId

  • GET - Read a shipment notice container (O)
  • PUT - Update a shipment notices container (O)
  • DELETE - Delete a shipment notices container (O)

• /shipmentNotices/:shipmentNoticeId

  • GET - Read a shipment notice (O)
  • PUT - Update a shipment notice (O)
  • DELETE - Delete a shipment notice (O)

• /shipmentNotices/:shipmentNoticeId/containers

  • GET - Read a shipment notice's containers (O)

• /thngs

  • POST - Create a Thng (O, T, U)
  • GET - Read all Thngs (O, T, U)

• /thngs/:thngIdentifier/actions/commissions

  • POST - Commission a Thng (O, T, U)

• /thngs/:thngIdentifier/actions/decommissions

  • POST - Decommission a Thng (O, T, U)

• /thngs/:thngIdentifier/commissionState

  • GET - Read Thng commissioning state (O, T, U)

• /thngs/:thngId

  • GET - Read a Thng (O, T, U, D)
  • PUT - Update a Thng (O, T, U, D)
  • DELETE - Delete a Thng (O, T)

• /thngs/:thngId/actions/:actionType

  • POST - Create a Thng action (O, T, U, D)
  • GET - Read all Thng actions (O, T, U, D)

• /thngs/:thngId/actions/:actionType/:actionId

  • GET - Read a Thng action (O, T, U, D)

• /thngs/:thngId/location

  • GET - Read a Thng's location (O, T, U, D)
  • PUT - Update a Thng's location (O, T, U, D)
  • DELETE - Delete a Thng location history (O, T)

• /thngs/:thngId/properties

  • POST - Create/update Thng properties (O, T, U, D)
  • GET - Read all Thng properties (O, T, U, D)

• /thngs/:thngId/properties/:propertyKey

  • PUT - Update a Thng property (O, T, U, D)
  • GET - Read a Thng property (O, T, U, D)
  • DELETE - Delete a Thng property (O, T)

• /thngs/:thngId/redirector

  • POST - Create a Thng's redirection (O, T, U)
  • GET - Read a Thng's redirection (O, T, U, D)
  • PUT - Update a Thng's redirection (O, T, U)
  • DELETE - Delete a Thng's redirection (O, T)

• /users

  • GET - Read all Application Users (O, T)

• /users/login

  • POST - Log In with Access Info (T, A)

• /users/:evrythngUser

  • GET - Read an Application User (O, T, U)
  • PUT - Update an Application User (O, U)
  • DELETE - Delete an Application User (O)

• /users/:evrythngUser/status

  • GET - Read an Application User's activation status (O, U)

---

### Redirections

https://tn.gg (or region equivalent)

• /redirections

  • POST - Create a redirection (O)

• /redirections/:shortId

  • GET - Read a redirection (O)
  • PUT - Update a redirection (O)
  • DELETE - Delete a redirection (O)

• /redirections/:shortId/ir

  • POST - Create an IR reference image (O)
  • GET - Read all IR reference images (O)

• /redirections/:shortId/ir/:id

  • GET - Read an IR reference image (O)
  • DELETE - Delete an IR reference image (O)

• /:shortId.{qr|png|svg|pdf}

  • GET - Generate a QR code (n/a)

---

Other

http://time.evrythng.com

• /time
  • GET - Read the current time (n/a)

https://auth.evrythng.com

• /oauth/authorize
  • GET - Request a user token for OAuth (U)

mqtts://mqtt.evrythng.com

• /
  • MQTT - Connect to the Pub/Sub Broker

wss://ws.evrythng.com

• /mqtt
  • MQTT (over secure WebSockets) - Connect to the Pub/Sub Broker