Token Management API

Token management enables listing, adding, and removing access tokens. Access tokens are associated with a device owner and may be associated with specific capabilities. These capabilities are:

  • dev:rd: Tokens with this capability may list and read the state of a device

  • dev:mgmt: Tokens with this capability may add or remove devices

  • dev:up: Tokens with this capability may specify uplinks for a device

  • dev:dn: Tokens with this capability may issue device requests

  • tok:rd: Tokens with this capability may list tokens

  • tok:mgmt: Tokens with this capability may add or remove tokens

  • gnss:rd: Tokens with this capability may download the almanac

List Tokens

GET /api/v1/token/list

Request the list of tokens associated with the owner account of the calling token.

Request Headers

Request Body:

No request body is required.

Response:

Status Codes
Response Headers

Response JSON:

If successful, the result field of the response points to a response object in the following format.

{
   "tokens":   [ TOKENINFO, .. ]  // Required. List of tokens
}

  • tokens: Required. List of token information (TokenInfo).

Example Request:

GET /api/v1/token/list HTTP/1.1
Host: mgs.loracloud.com
Content-Type: application/json

{}

Example Response:

{
   "result": {
       "tokens": [ ... ]
   },
   "errors": []
}

Renew or Rename Token

PUT /api/v1/token/(string: TOKEN)

Renames or renews a token.

Query Parameters

  • name (string) – Optional. New token name.

  • renew (boolean) – Optional. If specified, renews a token.

Request Headers

The target token is specified in the URI.

Response:

Status Codes
Response Headers

Response JSON:

If successful, the result field contains a TokenInfo object.

Example Request:

PUT /api/v1/token/AQEA4q5r...FFF?renew  HTTP/1.1
Host: mgs.loracloud.com
Content-Type: application/json

Example Response:

{
  "name": "token-name",
  "token": "AQEA4q5rf72WjyzaVDntiAm/+H2LKQpcWjzRdzfmWoCbqgB9pNoYyJI7X9dyFHa+Uu4xnlq5hw==",
  "capabilities": [ 'dev:mgmt', 'tok:mgmt' ]
}

Add Token

POST /api/v1/token/add

Adds a token for an account.

Request Body:

Include optional names or capabilities in the body of the request.

Note: This call does not allow capabilities to be escalated.

{
  "name":         STRING, // Optional. Token name.
  "capabilities": STRING  // Optional. List of capabilities.
}

  • name: Optional. Token name. By default, this is designated by the Device & Application Services.

  • capabilities: Optional. Token capabilities. By default, these capabilities match those of the authentication token.

Response JSON:

If successful, the result field contains a TokenInfo object.

Remove Token

DELETE /api/v1/token/(string: TOKEN)

Deletes a token.

Request Headers

The token to be deleted must be specified in the URI.

Response:

Status Codes
Response Headers

Response JSON:

If the token existed and was deleted, True. If the token did not exist, False. In both cases the token does not exist after the execution of the call

Get Token Info

GET /api/v1/token/(string: TOKEN)

Returns token informatiion.

Request Headers

The token to be queried must be specified in the URI.

Response JSON:

If successful, the “result” field contains a TokenInfo object.

Token Management JSON Formats

Token Info

Token information.

TOKENINFO = {
  "name":         STRING,  // Required. Name of token
  "token":        STRING,  // Required. The token itself
  "capabilities": [ STRING, .. ] // Required. List of token capabilities
  "owner":        INT      // Device owner ID
}

Capabilities include:

  • ‘dev:mgmt’: token holder may add or remove devices

  • ‘dev:up’: token holder may send uplinks to devices

  • ‘dev:dn’: token holder may request device actions

  • ‘dev:rd’: token holder may read devices

  • ‘tok:rd’: token holder may read token information

  • ‘tok:mgmt’: token holder may add or remove tokens