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 Key Scopes and Permissions

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. Each endpoint is listed in a nested format to be concatenated to the end of the level above for the full URL.

For example, the /validate endpoint constructed with its parent segments becomes
https://api.evrythng.com/auth/evrythng/users/:evrythngUser/validate.

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 info (O, A, U, T, D)
/accounts
  GET - Read account info (O)
  PUT - Update account info (O)

  /:accountId
    GET - Read account info by :accountId (O)
    PUT - Update account info by :accountId (O)

    /accesses
      GET - Read an account's accesses (O)

      /:accessId
        GET - Read an account access
        PUT - Update an account's access (O)

    /shortDomains
      GET - Read account short domains (O)
/actions
  POST - Create an action type (O, T)
  GET - Read all action types (O, U, T)
  DELETE - Delete an action type (O)

  /:actionType
    POST - Create an action by :actionType (O, U, T)
    GET - Read all actions by :actionType (O, U, T)
    PUT - Update an action by :actionType (O)
    DELETE - Delete an :actionType action type (O, T)

    /:actionId
      GET - Read a :actionType action by :actionId (O, U, T)
      DELETE - Delete a :actioType action by :actionId (O)

  /scans
    POST - Create a scan action (special case) (A)
/applications
  /me
    GET - Read the authenticating Application (A, T)
    PUT - Update the authenticating Application (T)
/auth
  /all
    /logout
      POST - Log the authenticating Application User out of all logins (U)

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

    /users
      POST - Create an Application User (A, T)

      /:evrythngUser
        /validate
          POST - Activate an Application User (A, T)

    /thngs
      POST - Create a Device API key for a Thng (O, U, T)

      /:thngId
        GET - Read the :thngId's Device API key (O, U, T)
        DELETE - Delete :thngId's Device API key (O, U, T)

  /facebook
    POST - Log a user in via Facebook (A, T)
/batches
  POST - Create a batch (O)
  GET - Read all batches (O)

  /:batchId
    GET - Read a batch by :batchId (O)
    PUT - Update a batch by :batchId (O)
    DELETE - Delete a batch by :batchId (O)

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

      /:taskId
        GET - Read a task by :taskId (O)

        /logs
          GET - Read a task on batch logs (O)
/collections
  POST - Create a collection (O, U, T)
  GET - Read all collections (O, U, T)

  /:collectionId
    GET - Read a collection by :collectionId (O, U, T)
    PUT - Update a collection by :collectionId (O, U, T)
    DELETE - Delete a collection by :collectionId (O, T)

    /actions
      /:actionType
        POST - Create an action on a collection (O, U, T)
        GET - Read all actions on a collection (O, U, T)

        /:actionId
          GET - Read a single action on a collection (O)

    /thngs
      GET - Read all Thngs in a collection by :collectionId (O, U, T)
      PUT - Add Thngs to a collection by :collectionId (O, U)
      DELETE - Delete all Thngs in a collection by :collectionId (O, T)

      /:thngId
        DELETE - Delete a Thng from a collection by :thngId (O, U, T)

    /collections
      POST - Add collections to a collection (O, U, T)
      GET - List all collections in a collection (O, U, T)
      DELETE - Delete all collections from a collection (O, T)

      /:childCollectionId
        DELETE - Delete a collection from a collection (O)
/connectors
  GET - Read all connectors (U)

  /:connectorName
    GET - Read a connector by name (U)

    /auth
      GET - Grant access to nest user (U)

      /token
        POST - Authenticate with a 3rd party service with an existing OAuth token (U)
/files
  POST - Create file metadata (O)
  GET - Read all files (O)

  /:fileId
    GET - Read a file by :fileId (O)
    PUT - Update a file by :fileId (O)
    DELETE - Delete a file by :fileId (O)
/places
  POST - Create a place (O, T)
  GET - Read all places (O, A, U, T)

  /:placeId
    GET - Read a place by :placeId (O, A, U, T)    
    PUT - Update a place by :placeId (O, T)
    DELETE - Delete a place by :placeId (O, T)
/products
  POST - Create a product (O, U, T)
  GET - Read all products (O, A, U, T)

  /:productId
    GET - Read a product by :productId (O, A, U, T)
    PUT - Update a product by :productId (O, U, T)
    DELETE - Delete a product by :productId (O, T)

    /actions
      /:actionType
        POST - Create an action on a product (O, U, T)
        GET - Read all actions on a product (O, U, T)

        /:actionId
          GET - Read a single action on a product (O, U, T)

    /properties
      POST - Create/update multiple properties (O, U, T)
      GET - Read all properties (O, A, U, T)
      PUT - Update multiple properties (O, U, T)

      /:key
        GET - Read a single property by :key (O, A, U, T)
        PUT - Update a single property by :key (O, U, T)
        DELETE - Delete property history by :key (O, U, T)

    /redirector
      POST - Create the products's redirection (O, U, T)
      GET - Read the products's redirection (O, U, T)
      PUT - Update the products's redirection (O, U, T)
      DELETE - Delete the products's redirection (O, T)
/projects
  POST - Create a project (O)
  GET - Read all projects (O)

  /:projectId
    GET - Read a project by :projectId (O)
    PUT - Update a project by :projectId (O)
    DELETE - Delete a project by :projectId (O)

    /applications
      POST - Create an application in :projectId (O)
      GET - Read all applications in :projectId (O)

      /:applicationId
        GET - Read an application by :applicationId (O)
        PUT - Update an application by :applicationId (O)
        DELETE - Delete an application by :applicationId (O)

        /secretKey
          GET - Read the Trusted Application API key (O)

        /connectors
          POST - Create a connector (O)
          GET - Read all connectors (O)

          /:connectorName
            GET - Read a connector by :connectorName (O)
            PUT - Update a connector by :connectorName (O)
            DELETE - Delete a connector by :connectorName (O)

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

          /:clientId
            GET - Read an OAuth client by :clientId (O)
            PUT - Update an OAuth client by :clientId (O)
            DELETE - Delete an OAuth client by :clientId (O)

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

            /:scheduleId
              GET - Read a Reactor schedule by :scheduleId (O, T)
              PUT - Update a Reactor schedule by :scheduleId (O, T)
              DELETE - Delete a Reactor schedule by :scheduleId (O, T)

          /script
            GET - Read the Reactor script (O)
            PUT - Update the Reactor script (O)

            /status
              GET - Read the Reactor script upload status (O)

          /logs
            GET - Read the Reactor logs (O)
            DELETE - Delete the Reactor logs (O)

        /redirector
          GET - Read the application redirector (O)
          PUT - Update the application redirector (O)
/rateLimits
  GET - Read the account's rate limit info (O, A, U, T, D)
/redirector
  GET - Read the account redirector (O)
  PUT - Update the account redirector (O)
/roles
  POST - Create a role (O)
  GET - Read all roles (O, U)

  /:roleId
    GET - Read a role by :roleId (O)
    PUT - Update a role by :roleId (O)
    DELETE - Delete a role by :roleId (O)

    /permissions  
      GET - Read a role's permissions (O)
      PUT - Set a new list of Application User role permissions (O)

      /:permissionName
        PUT - Enable/disable an Operator role permission by :permissionName (O)
/scan/identifications
  POST - Identify from image (A, T)
  GET - Retrieve identifier's resource from encoded value (A, T)
/schemas
  POST - Create a schema (O)
  GET - Read all schemas (O)

  /:schemaId
    GET - Read a schema by :schemaId (O)
    PUT - Update a schema by :schemaId (O)
    DELETE - Delete a schema by :schemaId (O)

    /policies
      GET - Read all policies for a given schema (O)

      /:policyId
        GET - Read a policy by :policyId (O)
        DELETE - Delete a policy by :policyId (O)
/thngs
  POST - Create a Thng (O, U, T)
  GET - Read all Thngs (O, U, T)

  /:thngId
    GET - Read a Thng by :thngId (O, U, T, D)
    PUT - Update a Thng by :thngId (O, U, T, D)
    DELETE - Delete a Thng by :thngId (O, T)

    /actions
      /:actionType
        POST - Create an action on a Thng of a certain type (O, U, T, D)
        GET - Read all actions on a Thng of a certain type (O, U, T, D)

        /:actionId
          GET - Read a single action on a Thng (O, U, T, D)

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

    /properties
      POST - Create/update multiple properties (O, U, T, D)
      GET - Read all properties (O, U, T, D)
      PUT - Update multiple properties (O, U, T, D)

      /:key
        GET - Read a single property by :key (O, U, T, D)
        PUT - Update a single property by :key (O, U, T, D)
        DELETE - Delete property history by :key (O, T)

    /redirector
      POST - Create the Thng's redirection (O)
      GET - Read the Thng's redirection (O, U, T, D)
      PUT - Update the Thng's redirection (O)
      DELETE - Delete the Thng's redirection (O)
/users
  GET - Read all Application Users in the account (O, T)
  PUT - Update an Application User in the account (O, T)
  DELETE - Delete an Application User in the account (O)

  /:evrythngUser
    GET - Read an Application User by :evrythngUser (O, U)
    PUT - Update an Application User by :evrythngUser (O, U)
    DELETE - Delete an Application User by :evrythngUser (O)

    /status
      GET - Read the Application User's activation status (O)

Redirections

https://tn.gg

/redirections
  POST - Create a redirection (O)
  GET - Read a redirection (O)
  PUT - Update a redirection (O)
  DELETE - Delete a redirection (O)
/:shortId.{qr|png|svg|pdf}
  GET - Generate a QR code (NONE)

Other

http://time.evrythng.com

/time
  GET - Read the current time (NONE)

https://auth.evrythng.com

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

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

API Key Scopes and Permissions