EVRYTHNG Developer Hub

Welcome! Here's where you'll find what you need to start working with EVRYTHNG as quickly as possible. There are comprehensive guides, documentation, and support if you get stuck. We encourage you to dive in and explore.

Create Free Account Read Documentation

API Scope and Key Permissions

In the EVRYTHNG Platform there are two concepts governing how different actors (users, devices, etc.) can interact with the various resource types. These are called permissions and scopes. In short, permissions determine what a user can read/modify while scopes determine what a user can see.

Permissions

Each time a REST call is performed, the platform checks that the API key exists, and that the provided API key permissions allow that call to be made. This check is based on the request URL, HTTP verb, and query parameters. If this security check does not pass the response will be 403 Forbidden. See below for more information about permissions.

Scopes

The API key is also used to define the scope of the request - e.g, 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 project within that account.

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 the scope as a filter applied to account resources. If you try to access a resource with the wrong 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

Account Scope

Each API key is linked to a single Dashboard Account. Resources (Thngs, products) created with an API key are therefore created within the corresponding account. Other API keys associated with the same account will also be able to see those resources.

Note

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

Project Scope

As shown in the scope table, the API Key defines which account we are viewing and optionally, which project within that account we are scoped to.

Imagine a hypothetical account containing two projects. The visibility of the resources stored within those projects will vary depending on the type of API key used.

In the case of a request authenticated with an Operator key, the entire account contents are visible. This is described as having "no project scope". Still using the Operator key, we can scope into a specific project using the query parameter ?project. This is described as a "Project-scoped request".

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.

The project scope of a resource is set upon creation based on the scope of the project-scoped request. However, unlike the account scope, a resource's project scope can be modified later on. Additionally, a resource can exist within the scopes of multiple projects within the same account.

Resources created without a project-scoped request are not visible to any project. In this case, no project-scoped request can see this resource.

As an Operator, if you want your applications and users to interact with your resources, you must have them in the project scope, by either:

  • Creating them with a project-scoped request.
  • Modifying their scope after creation to be visible as required.

User Scope

As we have seen, the Application User API keys also defines a user scope. As for the project scope, the user scope of resources can be updated afterwards through a PUT request on the resource.

The initial value of the user scope depends of the project scope used for the creation request, 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.

Note

The ?userScope query parameter can only be used to update the scope of a resource.


Scope of API Keys

The different types of API keys provide different scope filters, as the table below shows:

API Key
Project Scope
User Scope

Operator

None or optionally specified with ?project

None

Application

Fixed

None

Application User

Fixed

Fixed

Trusted Application

Fixed

None

Device

If a Device key is obtained using an Application User key, it is scoped to the relevant project. However, if a Device key is obtained using an Operator key, it is not scoped to a project (unless specified with ?project).

None


API Key Permissions

There are five types of API Key that are used in different contexts when interacting with the REST API:

  1. Operator Key
  2. Application Key
  3. Application User Key
  4. Trusted Application Key
  5. Device Key

The following lists show the rights associated with each of these different types of key for the Create (POST), Read (GET), Update (PUT), and Destroy (DELETE) operations.


Operator API Key

An Operator API Key will be generated when an Operator user creates a new account. An Operator creating several accounts will get a new Operator key for each one. This key can be regenerated at any time through the Dashboard in 'Account Settings' if compromised.

The Operator API Key gives full access to your account and therefore must be kept secret (e.g. only used in private server code) to prevent any abuse.

  • /accounts - GET
    Read self account information. Including short domains and API keys.

  • /accounts/:accountId/accesses - GET, PUT
    Manage account roles and permissions.

  • /actions - POST, GET, PUT, DELETE
    Manage action types.

  • /actions/:type - POST, GET, DELETE
    Perform actions, view actions performed.

  • /auth/evrythng/thngs - POST, GET, DELETE
    Manage device API keys.

  • /batches - POST, GET, PUT, DELETE
    Manage batches.

  • /batches/:batchId/tasks - POST, GET
    Manage tasks on batches.

  • /collections - POST, GET, PUT, DELETE
    Manage collection resources.

  • /files - POST, GET, PUT, DELETE
    Manage file storage.

  • /jobs - POST, GET
    Manage jobs.

  • /places - POST, GET, PUT, DELETE
    Manage places.

  • /products - POST, GET, PUT, DELETE
    Manage product resources.

  • /projects - POST, GET, PUT, DELETE
    Manage projects.

  • /projects/:projectId/applications - POST, GET, PUT, DELETE
    Manage project applications.

  • /projects/:projectId/applications/:applicationId/connectors - POST, GET, PUT, DELETE
    Manage application Cloud-to-Cloud connectors.

  • /projects/:projectId/applications/:applicationId/oauthClients - POST, GET, PUT, DELETE
    Manage application OAuth capabilities.

  • /projects/:projectId/applications/:applicationId/reactor - POST, GET, PUT, DELETE
    Manage application Reactor logs, scripts, and schedules.

  • /projects/:projectId/applications/:applicationId/redirector - POST, GET, PUT, DELETE
    Manage application Redirector.

  • redirector - GET, PUT
    Manage account Redirector.

  • /roles - POST, GET, PUT, DELETE
    Manage account roles.

  • /roles/:roleId/permissions - GET, PUT
    Manage role permissions.

  • /scan/identifications - POST, GET
    Identifier and image recognition.

  • /thngs - POST, GET, PUT, DELETE
    Manage Thng resources.

  • https://tn.gg/redirections - POST, GET, PUT, DELETE
    Manage redirections short IDs, QR codes and reference images.

  • /users - GET, PUT, DELETE
    Manage Application Users.


Application API Key

The Application API Key is restricted and can be used to bootstrap an application as well as to create and identify Application Users. Its typical use is within a client web/mobile application and hence can safely be visible in code. This key is not a secret but an application identifier.

  • /actions/scans - POST
    Perform scan actions.

  • /applications/me - GET
    Information about self application.

  • /auth/evrythng - POST
    Create and authenticate EVRYTHNG users using email password pair.

  • /auth/facebook - POST
    Create and authenticate users via Facebook.

  • /places - GET
    Manage places.

  • /products - GET
    View product resources.

  • /scan/identifications - POST, GET
    Perform QR code / barcode recognition using image.


Application User API Key

The Application User API Key is generated after user authentication (e.g. through Facebook), and grants extra privileges. This is the key to use when interacting with resources or creating actions, etc. This key is a secret generated at runtime and should not be hardcoded in client side code (e.g., web app Javascript) as it will expire if the user is logged out.

  • /access - GET
    Read key information.

  • /actions - GET
    Read available action types.

  • /actions/:type - POST, GET
    Perform actions, view action performed.

  • /auth/all/logout - POST
    Logout and invalidate Application User API key.

  • /auth/evrythng/thngs - POST, GET, DELETE
    Access device API keys for Thngs in user's scope.

  • /collections - POST, GET, PUT
    Interact with collection resources.

  • /collections/:collectionId/thngs - DELETE
    Delete Thngs within collections.

  • /connectors - GET
    Discover and use Cloud-to-Cloud connectors.

  • /connections/:connectorName/auth - GET, DELETE
    Manage third party connector authentications.

  • /places - GET
    Read places.

  • /products - POST, GET, PUT
    Interact with product resources.

  • /rateLimits - GET
    Read key access rate limit information.

  • /thngs - POST, GET, PUT
    Interact with Thng resources.

  • /users/:userId - GET, PUT
    Read / update self user data.


Trusted Application API Key

The Trusted Application API Key belongs to an application and can be read by an Operator. It is a secret key to be used only by backend applications whose code is not exposed e.g: Ruby, PHP, Java or Node apps. It should not be used in client side applications (e.g: JavaScript web apps).

  • /actions - POST, GET
    Interact with actions.

  • /actions/:type - POST, GET, DELETE
    Interact with action types.

  • /applications/me - GET, PUT
    Interact with the application this key is bound to.

  • /auth/evrythng - POST
    Authenticate the user via EVRYTHNG Auth API.

  • /auth/evrythng/thngs - POST, DELETE
    Create and delete Device API keys.

  • /auth/facebook - POST
    Interact with users via external profiles.

  • /collections - POST, GET, PUT, DELETE
    Manage collection resources.

  • /places - POST, GET, PUT, DELETE
    Interact with places.

  • /products - POST, GET, PUT, DELETE
    Manage product resources.

  • /projects/:projectId/applications/:applicationId/reactor/schedules - POST, GET, PUT, DELETE
    Application Reactor schedules.

  • /projects/:projectId/applications/:applicationId/reactor/logs/bulk - POST
    Application Reactor logs.

  • /scan/identifications - POST, GET
    Identifier and image recognition.

  • /thngs - POST, GET, PUT, DELETE
    Manage Thng resources.

  • /users - GET
    Interact with users.


Device API Key

The Device API Key is generated for an existing Thng and grants privileges to update the state of the device. The thngId in the list below refers to the ID of the device's Thng.

  • /thngs/:thngId/actions - POST, GET
    Interact with actions on the device.

  • /thngs/:thngId/actions/:type - POST, GET
    Interact with actions of a specific type on the device.

  • /thngs/:thngId - GET, PUT
    Interact with the device metadata.

  • /thngs/:thngId/location - POST, GET, PUT
    Interact with the device location.

  • /thngs/:thngId/properties - POST, GET, PUT
    Interact with the device properties.


All Types of Key

In addition the the above listed permissions, each API key is able to perform the following calls:

  • /access - GET
    Read information about this key.

  • /rateLimits - GET
    Read key requests allowance and usage.

API Scope and Key Permissions