Docs

Appearance

Open console

Reference

Access Tokens

REST API reference for Access Tokens: create, read, update, clone and delete access tokens. 8 operations.

Reference6 min read

For the base URL, authentication and errors, see the REST API overview.

GET /v1/users/{user}/tokens ​

  • Request: GET /v1/users/{user}/tokens
  • Operation: ListTokens
  • Operation ID: Token_List
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/tokens' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

Response example (200)

json
[
  {
    "created": 1792263090744,
    "enabled": true,
    "modified": 1792263090744,
    "name": "Admin Access",
    "token": "admin_access"
  },
  {
    "created": 1792263090744,
    "enabled": true,
    "modified": 1792263090744,
    "name": "Shared Access",
    "token": "shared_access"
  },
  {
    "created": 1792263090744,
    "enabled": true,
    "modified": 1792263090744,
    "name": "Greenhouse 01",
    "token": "greenhouse_01_access"
  },
  {
    "created": 1792263090744,
    "enabled": true,
    "modified": 1792263090744,
    "name": "Read-only dashboard",
    "token": "readonly_dashboard"
  }
]

POST /v1/users/{user}/tokens ​

  • Request: POST /v1/users/{user}/tokens
  • Operation: CreateToken
  • Operation ID: Token_Create
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
allowobjectno
allow.*objectnoMinimum properties: 1
allow.*.*string or array of string or objectno
allow.*.*stringnoPattern: ^[a-zA-Z0-9_\*]{1,64}$|^\*$Variant 1:
allow.*.*array of string or objectnoVariant 2:
allow.*.*[]stringnoPattern: ^[a-zA-Z0-9_\*]{1,64}$|^\*$Variant 2: Variant 1:
allow.*.*[]objectnoVariant 2: Variant 2:
allow.*.*[].*string or array of stringnoVariant 1: Pattern: ^[a-zA-Z0-9_\*]{1,32}$|^\*$Variant 2: Variant 2:
denyobjectno
deny.*objectnoMinimum properties: 1
deny.*.*string or array of string or objectno
deny.*.*stringnoPattern: ^[a-zA-Z0-9_\*]{1,64}$|^\*$Variant 1:
deny.*.*array of string or objectnoVariant 2:
deny.*.*[]stringnoPattern: ^[a-zA-Z0-9_\*]{1,64}$|^\*$Variant 2: Variant 1:
deny.*.*[]objectnoVariant 2: Variant 2:
deny.*.*[].*string or array of stringnoVariant 1: Pattern: ^[a-zA-Z0-9_\*]{1,32}$|^\*$Variant 2: Variant 2:
descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
enabledbooleanyes
expirenumbernoExpiration as a unix timestamp in milliseconds: the token stops working then, and is deleted shortly after. Without it the token does not expire. Set when the token is created; it cannot be changed later.
namestringyesMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.
tokenstringyesPattern: ^[a-zA-Z0-9_]{1,50}$

Example request: Admin Access

bash
curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/tokens' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "allow": {
    "*": {
      "*": "*"
    }
  },
  "enabled": true,
  "name": "Admin Access",
  "token": "admin_access"
}'

Example body: Custom Access

json
{
  "allow": {
    "Bucket": {
      "mqtt_bucket": [
        "ReadBucket"
      ]
    },
    "Device": {
      "*": [
        "AccessDeviceResources"
      ]
    }
  },
  "enabled": true,
  "name": "Shared Access",
  "token": "shared_access"
}

Example body: One device

json
{
  "allow": {
    "Bucket": {
      "greenhouse_climate": [
        "ReadBucket"
      ]
    },
    "Device": {
      "greenhouse_01": [
        "Read*",
        "AccessDeviceResources"
      ]
    }
  },
  "enabled": true,
  "name": "Greenhouse 01",
  "token": "greenhouse_01_access"
}

Example body: Read-only devices and buckets

json
{
  "allow": {
    "Bucket": {
      "*": [
        "List*",
        "Read*"
      ]
    },
    "Device": {
      "*": [
        "List*",
        "Read*"
      ]
    }
  },
  "enabled": true,
  "name": "Read-only dashboard",
  "token": "readonly_dashboard"
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/tokens/{token} ​

  • Request: GET /v1/users/{user}/tokens/
  • Operation: ReadTokenConfig
  • Operation ID: Token_ReadConfig
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
tokenpathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/tokens/YOUR_TOKEN' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

Response example (200, Admin Access)

json
{
  "allow": {
    "*": {
      "*": "*"
    }
  },
  "created": 1792263090744,
  "enabled": true,
  "modified": 1792263090744,
  "name": "Admin Access",
  "token": "admin_access"
}

Response example (200, Custom Access)

json
{
  "allow": {
    "Bucket": {
      "mqtt_bucket": [
        "ReadBucket"
      ]
    },
    "Device": {
      "*": [
        "AccessDeviceResources"
      ]
    }
  },
  "created": 1792263090744,
  "enabled": true,
  "modified": 1792263090744,
  "name": "Shared Access",
  "token": "shared_access"
}

Response example (200, One device)

json
{
  "allow": {
    "Bucket": {
      "greenhouse_climate": [
        "ReadBucket"
      ]
    },
    "Device": {
      "greenhouse_01": [
        "Read*",
        "AccessDeviceResources"
      ]
    }
  },
  "created": 1792263090744,
  "enabled": true,
  "modified": 1792263090744,
  "name": "Greenhouse 01",
  "token": "greenhouse_01_access"
}

Response example (200, Read-only devices and buckets)

json
{
  "allow": {
    "Bucket": {
      "*": [
        "List*",
        "Read*"
      ]
    },
    "Device": {
      "*": [
        "List*",
        "Read*"
      ]
    }
  },
  "created": 1792263090744,
  "enabled": true,
  "modified": 1792263090744,
  "name": "Read-only dashboard",
  "token": "readonly_dashboard"
}

PUT /v1/users/{user}/tokens/{token} ​

  • Request: PUT /v1/users/{user}/tokens/
  • Operation: UpdateToken
  • Operation ID: Token_Update
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
tokenpathstringyes

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
allowobjectno
allow.*objectnoMinimum properties: 1
allow.*.*string or array of string or objectno
allow.*.*stringnoPattern: ^[a-zA-Z0-9_\*]{1,64}$|^\*$Variant 1:
allow.*.*array of string or objectnoVariant 2:
allow.*.*[]stringnoPattern: ^[a-zA-Z0-9_\*]{1,64}$|^\*$Variant 2: Variant 1:
allow.*.*[]objectnoVariant 2: Variant 2:
allow.*.*[].*string or array of stringnoVariant 1: Pattern: ^[a-zA-Z0-9_\*]{1,32}$|^\*$Variant 2: Variant 2:
denyobjectno
deny.*objectnoMinimum properties: 1
deny.*.*string or array of string or objectno
deny.*.*stringnoPattern: ^[a-zA-Z0-9_\*]{1,64}$|^\*$Variant 1:
deny.*.*array of string or objectnoVariant 2:
deny.*.*[]stringnoPattern: ^[a-zA-Z0-9_\*]{1,64}$|^\*$Variant 2: Variant 1:
deny.*.*[]objectnoVariant 2: Variant 2:
deny.*.*[].*string or array of stringnoVariant 1: Pattern: ^[a-zA-Z0-9_\*]{1,32}$|^\*$Variant 2: Variant 2:
descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
enabledbooleanno
expirenumbernoCannot be changed: the expiration is signed into the token when it is created. Create a new token instead.
namestringnoMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.

Example request: Full Update

bash
curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/tokens/YOUR_TOKEN' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "allow": {
    "*": {
      "*": "*"
    }
  },
  "enabled": true,
  "name": "Admin Access",
  "token": "admin_access"
}'

Example body: Update 'allow'

json
{
  "allow": {
    "*": {
      "*": "*"
    }
  }
}

Example body: Update 'enabled'

json
{
  "enabled": true
}

Example body: Update 'name'

json
{
  "name": "Admin Access"
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

DELETE /v1/users/{user}/tokens/{token} ​

  • Request: DELETE /v1/users/{user}/tokens/
  • Operation: DeleteToken
  • Operation ID: Token_Delete
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
tokenpathstringyes

Example request

bash
curl -X DELETE 'https://YOUR_SERVER/v1/users/YOUR_USER/tokens/YOUR_TOKEN' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/tokens/{token}/clone ​

  • Request: GET /v1/users/{user}/tokens/{token}/clone
  • Operation: CloneTokenConfig
  • Operation ID: Token_CloneConfig
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
tokenpathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/tokens/YOUR_TOKEN/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

POST /v1/users/{user}/tokens/{token}/clone ​

  • Request: POST /v1/users/{user}/tokens/{token}/clone
  • Operation: CloneToken
  • Operation ID: Token_Clone
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
tokenpathstringyes

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
enabledbooleanno
namestringnoMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.
tokenstringyesPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.

Example request: Copy with a new id

bash
curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/tokens/YOUR_TOKEN/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "token": "copy_of_token"
}'

Example body: Copy with name and description

json
{
  "description": "Same configuration as the original, for production line 2",
  "name": "Line 2 copy",
  "token": "line_2_token"
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

PUT /v1/users/{user}/tokens/{token}/projects ​

  • Request: PUT /v1/users/{user}/tokens/{token}/projects
  • Operation: UpdateTokenProjects
  • Operation ID: Token_UpdateProjects
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
tokenpathstringyes

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
(body)array of stringnoProjects the resource belongs to, as <owner>@<project> ids. Replaces the whole list: read the current one first to add or remove a single project; [] removes it from every project.

Example request: No projects

bash
curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/tokens/YOUR_TOKEN/projects' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[]'

Example body: One project

json
[
  "YOUR_USER@greenhouse"
]

Example body: Two projects

json
[
  "YOUR_USER@greenhouse",
  "YOUR_USER@maintenance"
]

Responses

StatusDescription
200ok
401unauthorized
403forbidden