Skip to content

Tokens

The Embedthis Builder and Ioto use tokens to securely authenticate and authorize access to the builder and device clouds.

Each token can be used for a purpose that is specified via the token's type. When used for this purpose, the token bearer can assume the tokens role to act upon the system.

Token List

Tokens have the follow properties:

  • Type — the token purpose
  • Description — human readable token description
  • Enable — whether the token is currently enabled or disabled
  • Expires — the date upon which the token expires and cannot be used
  • Role — the authorized role the token bearer will assume
  • ID — the token ID to present when using the token for access
  • Cloud — the device cloud ID if the token is created by the device cloud

Token Type

The following token types are currently used by the Builder and Ioto

  • BuilderAPI — Used for general API access to the Builder API as an administrator.
  • ProductID — Used when registering devices in the device.json5 file.
  • CloudID — Used when claiming devices for management for a device cloud.
  • CloudToBuilder — Used by device clouds to issue requests to the builder.
  • BuilderToCloud — Used by the builder to issue requests to a device cloud.

Token Modify

Token Description

The token description may be modified to help you document the purpose of a specific token.

Token Enable

A token can be temporarily enabled or disabled. Should you experience a cyber attack or breach, you can immediately disable tokens to minimize the damage while you investigate. When all is clear, you can re-enable, revoke or reissue the tokens.

Token Expiry

Each token will expire on a specified date. You can modify tokens to change the expiry date.

Token Role

When a token is presented, it grants the access to the relevant resources using the token's role.

The following roles are supported:

  • public — Grants minimum privilege appropriate for unauthenticated users.
  • user — Grants read-only access at the "user" level.
  • admin — Grants administrator access which provides general read/write access.
  • owner — Grants administrator and owner access which provides access to billing.
  • device — Grants access suitable for a device.
  • builder — Grants access suitable for the builder to act upon a device cloud.

Token Actions

  • New — Create a new token. If you selected an existing token, the new token will clone the properties of the original token. The original token is not impacted.
  • Replace — An original token is expired and a new active token is created with the same type, description and role.
  • Resume — Resume a suspended token.
  • Suspend — Suspend a token. The expiry date is not changed.
  • Revoke — Revoke a token by setting the expiry date to the current time.

Using Tokens

When using REST APIs, you can present the token ID in the X-Token or Authorization HTTP headers. The format should be like:

1
X-Token: bearer 01GEZKE44ZX0C3B0ANF3ZF81CZ

From the token list, you can select the clipboard icon in the token's ID column to copy the ID to your PC's clipboard.