API/Device Tokens

API/Device tokens can be created when you want to integrate with a third party or device, but maintain authentication separation from your main user/secret. For instance, if you you want to provide a token to a third party, but maintain the right to revoke it later.

This becomes useful for managing IoT devices independently from your main user.

Using

Once you have a token id and secret, you can use them completely in-place of a user id/secret.

Eg. instead of /api/v1/user/{{userId}} you would put /api/v1/user/{{tokenId}}.

In your header, you would simply replace your user token with the auth token secret:

Authorization: Bearer {{tokenId}}

If you want to designate a token to be used by a specific client, you can associate a client_id with the token on-creation. Clients can not be changed once created. (eg. OIDC uses client_id to tightly couple a token with a plugin)

Scopes

Tokens have a set of scopes (separated by a space ) that specify what you are allowed to do with that given set of credentials.

Scope Operation Description
user Read Read info about user (except password)
user.update.password Update Update user details (password)
topic Read Read a topic and its subscriptions
topic.create Create Create a new topic for a user
topic.update Update Update an existing topic
topic.delete Delete Delete an existing topic
topic.* Any Create, Read, Update, Delete
subscription.create Create Create a new subscription on a topic
subscription.update Update Modify a subscription on a topic
subscription.delete Delete Remove a subscription from a topic
subscription.* Any Create, Update, Delete
token Read Read ALL exist tokens. WARNING: This includes secrets!
token.create Create Create a new token for a user
token.update Update Update an existing token for the user
token.delete Delete Delete an existing token for a user
token.* Any Create, Read, Update, Delete
event Read Read events for the user
event.series Read Read summarized data about events over time
event.* Read Both read endpoints
template Read Read templates the user has
template.exec Exec Execute a template with a payload
template.create Create Create a new template
template.update Update Update an existing template
template.delete Delete Delete an existing template
template.* Any Create, Read, Update, Delete (Not Exec)

For more information about which scopes apply to which endpoints, visit the Swagger Docs.

Authentication

You can authenticate externally with the OpenID Connect (OIDC) flow. Read more about it here