ActivateAuthenticateAmplify
API Reference
DashboardSupportDeveloper Blog

Access Tokens

In addition to human accesses - as an operator access - the platform also supports service accesses, so that services can interact with the platform on behalf of someone or something that does not have an account in the platform.
For example, a mobile application that anyone can download and use, or a software service that allows other services to use the EVRYTHNG product cloud platform in a way the service creator desires.

These interactions are not on behalf of authorised and signed Operators, but of anonymous users through the authorised service. This is is the purpose of service accesses, called Access Tokens.

🚧

Access tokens limit

An account is allowed a maximum of 100 Access Tokens.

The Access Tokens API allows the creation and management of access tokens. A given service signed into our platform and part of a certain account will have a service API Key that is unique per account.

Through the Access Tokens API Operators with allowed roles are able to create new Access Tokens for their accounts, assign roles and apply attribute based restrictions on each access token, so that services can only access data relevant to their context.

Upon creation of access tokens, their names, access policies and restrictive conditions must be provided. This will qualify their access in the platform.

API Status
General Availability:
/accessTokens

Jump To↓

AccessTokenDocument
Create an access token
Read service access tokens

AccessTokenDocument Data Model

An object representing an access token.

.name (string, required)
    The name of the access token.

.description (string)
    The description of the access token.  Which services this 
    token might be applied to.

.policies (array of string, max. 100, required)
    An array of policy IDs

.conditions (array of string, max. 256, required)
    A conditions array.

.tags (array of string)
    Array of string tags associated with this resource.

.identifiers (IdentifiersDocument)
    Various identifiers (EPC, GTIN, etc.) as a JSON object with 
    one or more key-value pairs.

.customFields (CustomFieldsDocument)
    Object of case-sensititve key-value pairs of custom fields 
    associated with the resource.

.apiKey (string)
    80 base64 characters length string to use to interact with the API.

{
  "additionalProperties": false,
  "type": "object",
  "description": "An object representing a service access.",
  "readOnly": true,
  "required": ["name", "conditions", "policies"],
  "properties": {
    "apiKey": {
      "description": "The access token.",
      "type": "string",
      "example": "XE1fH9SwzUrMB47Nu2tIMhvsrpkBXvhNnMMH9oEGTWxEI97Q0Mis8PA7YP58RcZEzQlHVdtoogELnYpE"
    },
    "name": {
      "description": "The name of the access token.",
      "type": "string",
      "example": "[email protected]",
      "minLength": 5,
      "maxLength": 128
    },
    "description": {
      "description": "The description of the access token.  Which services this token might be applied to.",
      "type": "string",
      "maxLength": 256
    },
    "policies": {
      "description": "An array of policy IDs",
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 24,
        "maxLength": 24
      },
      "uniqueItems": true,
      "maxItems": 100
    },
    "conditions": {
      "description": "A conditions array.",
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 3,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9_-]+:[A-Za-z0-9_-]+$"
      },
      "maxItems": 256,
      "uniqueItems": true
    },
    "tags": {
      "type": "array",
      "description": "Array of string tags associated with this resource.",
      "items": {
        "type": "string",
        "maxLength": 60
      }
    },
    "identifiers": {
      "type": "object",
      "description": "Various identifiers (EPC, GTIN, etc.) as a JSON object with one or more key-value pairs."
    },
    "customFields": {
      "type": "object",
      "description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
    }
  }
}

{
  "id": "UsFQTQPFKG7UHraab3wE3Fhb",
  "apiKey": "XE1fH9SwzUrMB47Nu2tIMhvsrpkBXvhNnMMH9oEGTWxEI97Q0Mis8PA7YP58RcZEzQlHVdtoogELnYpE",  
  "name": "Token Name",
  "description": "Mobile application access token",
  "policies": [
    "UPb7Eq8hwpktcaaabfahfpdq"
  ],
  "conditions": [
    "factoryId:U8wQCBT7KXa4xHc5aCQk5pab"
  ],
  "identifiers": {},
  "tags": [],
  "customFields": {},
  "createdAt": 1586442216863,
  "updatedAt": 1586442216863
}

Filterable Fields

This resource type can be filtered using the following fields and operators.

FieldTypeOperatorsExample
idsString=/accessTokens?filter=ids=VwwSgFqb9mdp6Qawxxxwceqk
policiesString=/accessTokens?filter=policies=UPb7E6shapktcaaabfahfpds
conditionsString=/accessTokens?filter=conditions=factoryId:20202020

Create an access token

Creates an access token for given account.

POST /accessTokens
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

AccessTokenDocument

curl -i -H Content-Type:application/json \
  -H Authorization:$OPERATOR_API_KEY \
  -X POST https://api.evrythng.io/v2/accessTokens \
  -d '{
  "name": "Token Name",
  "description": "Mobile application access token",
  "policies": [
    "UPb7Eq8hwpktcaaabfahfpdq"
  ],
  "conditions": [
    "factoryId:U8wQCBT7KXa4xHc5aCQk5pab"
  ],
  "identifiers": {},
  "tags": [],
  "customFields": {},
  "createdAt": 1586442216863,
  "updatedAt": 1586442216863
}'

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "UsFQTQPFKG7UHraab3wE3Fhb",
  "name": "Mobile App",
  "apiKey": "XE1fH9SwzUrMB47Nu2tIMhvsrpkBXvhNnMMH9oEGTWxEI97Q0Mis8PA7YP58RcZEzQlHVdtoogELnYpE",
  "description": "Mobile application access token",
  "policies": [
    "UPb7Eq8hwpktcaaabfahfpdq"
  ],
  "conditions": [
    "factoryId:U8wQCBT7KXa4xHc5aCQk5pab"
  ]
}

Read service access tokens

Read all service accesses for an account

GET /accessTokens
Authorization: $OPERATOR_API_KEY

curl -i \
  -H Authorization:$OPERATOR_API_KEY \
  -X GET https://api.evrythng.io/v2/accessTokens

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "UsFQTQPFKG7UHraab3wE3Fhb",
    "apiKey": "XE1fH9SwzUrMB47Nu2tIMhvsrpkBXvhNnMMH9oEGTWxEI97Q0Mis8PA7YP58RcZEzQlHVdtoogELnYpE",
    "name": "Mobile App",
    "description": "Mobile application access token",
    "policies": [
      "UPb7Eq8hwpktcaaabfahfpdq"
    ],
    "conditions": [
      "factoryId:U8wQCBT7KXa4xHc5aCQk5pab"
    ],
    "identifiers": {},
    "tags": [],
    "customFields": {},
    "createdAt": 1586442216863,
    "updatedAt": 1586442216863
  },
  {
    "id": "UsFQTQPFKG7UHraab3wE3Fhb",
    "apiKey": "XE1fH9SwzUrMB47Nu2tIMhvsrpkBXvhNnMMH9oEGTWxEI97Q0Mis8PA7YP58RcZEzQlHVdtoogELnYpE",
    "name": "Web App",
    "description": "Web application access token",
    "policies": [
      "UPb7Eq8hwpktcaaabfahfpdq"
    ],
    "conditions": [
      "factoryId:U8wQCBT7KXa4xHc5aCQk5pab"
    ],
    "identifiers": {},
    "tags": [],
    "customFields": {},
    "createdAt": 1586442216863,
    "updatedAt": 1586442216863
  }
]