Version: Mosquitto 2.9

Tokens

Application tokens that can provide access to the MMC to other applications and systems without the need for conventional login. In order to access MMC, when making a request put the token inside the "Authorization" header as "Bearer token" or use it as a url parameter ("https://url.com?token=*token*"). Also set the Accept header to "application/json;version=<version_number>" to access a ceorrect version of the api

Path: /api/tokens

Methods

GET

Returns information about all the application tokens. Can be used only by an admin user

Responses

Status Description Response Content or Scheme

200

List of objects with information on every application token

{
  "name": {
    "type": "string",
    "description": "Human-readable name of the token. Must be unique. 30 characters max. Anything logner will be truncated"
  },
  "hash": {
    "type": "string",
    "description": "Hash of the token"
  },
  "validUntil": {
    "type": "string",
    "description": "Datetime when the token validity expires. ISO 8601 datetime string"
  },
  "role": {
    "type": "string",
    "description": "Access role which is provided by the token",
    "enum": [
      "admin",
      "editor",
      "viewer",
      "connectionManager",
      "monitoringViewer"
    ]
  },
  "requestedBy": {
    "type": "string",
    "description": "User who generated the token or null if token was not reuqested by a user"
  },
  "issueDate": {
    "type": "string",
    "description": "Datetime when the token was generated. ISO 8601 datetime string"
  },
  "lastUsed": {
    "type": "string",
    "description": "Datetime when the token was last used. ISO 8601 datetime string"
  }
} 

Example

{
  "name": "mytoken1",
  "hash": "5e16b71e4aded06d1231d0b5ce2054475c6de39bf2f7d8f075836c42e67ce0a4",
  "validUntil": "2025-06-08T10:54:53.000Z",
  "role": "admin",
  "requestedBy": "rootUser",
  "issueDate": "2022-09-12T11:11:25.113Z",
  "lastUsed": "2022-09-12T11:11:25.113Z"
}

Status	Description	Response Content or Scheme
401	Access to resource is denied. User not authenticated (logged in) or session expired	`{ "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Unauthorized" ], "description": "Message of the error" } }`
403	User does not have enough permissions to access the resource	`{ "code": { "type": "string", "enum": [ "NOT_ALLOWED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Not allowed" ], "description": "Message of the error" } }`
404	Plugin is not enabled or not found	`{ "code": { "type": "string", "enum": [ "NOT_FOUND" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Plugin not found" ], "description": "Message of the error" } }`
500	An internal server error has occured	`{ "code": { "type": "string", "enum": [ "SOMETHING_WRONG", "INTERNAL_ERROR" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "An internal server error occurred" ], "description": "Message of the error" } }`

POST

Creates an application token. Can be used only by an admin user. After creating a token, in order to access MMC, when making a request put the token inside the "Authorization" header as "Bearer token" or use it as a url query parameter ("https://url.com?token=*token*")

Parameters

Name Required Type Request Properties or Schema

body

true

object

A token object.

Properties:

{
  "name": {
    "type": "string",
    "description": "Human-readable name of the token. Must be unique. 30 characters max. Anything logner will be truncated"
  },
  "validUntil": {
    "type": "string",
    "description": "Datetime when the token validity expires. ISO 8601 datetime string"
  },
  "role": {
    "type": "string",
    "description": "Access role which is provided by the token",
    "enum": [
      "admin",
      "editor",
      "viewer",
      "connectionManager",
      "monitoringViewer"
    ]
  }
} 

Example

{
  "name": "mytoken1",
  "validUntil": "2025-06-08T10:54:53.000Z",
  "role": "admin"
}

Responses

Status Description Response Content or Scheme

200

Token object

{
  "token": {
    "type": "string",
    "description": "The actual application token requested by the user"
  },
  "name": {
    "type": "string",
    "description": "Human-readable name of the token. Must be unique. 30 characters max. Anything logner will be truncated"
  },
  "hash": {
    "type": "string",
    "description": "Hash of the token"
  },
  "validUntil": {
    "type": "string",
    "description": "Datetime when the token validity expires. ISO 8601 datetime string"
  },
  "role": {
    "type": "string",
    "description": "Access role which is provided by the token",
    "enum": [
      "admin",
      "editor",
      "viewer",
      "connectionManager",
      "monitoringViewer"
    ]
  },
  "requestedBy": {
    "type": "string",
    "description": "User who generated the token or null if token was not reuqested by a user"
  },
  "issueDate": {
    "type": "string",
    "description": "Datetime when the token was generated. ISO 8601 datetime string"
  },
  "lastUsed": {
    "type": "string",
    "description": "Datetime when the token was last used. ISO 8601 datetime string"
  }
} 

Example

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYWRtaW4iLCJpYXQiOjE2NjI5ODM1MDAsImV4cCI6MTc0OTM4MDA5MywiaXNzIjoiY2VkYWxvIn0.NAVy_UB3Niiuxa2gGUzwvlahXds20rsJSApAkc6SPZc",
  "name": "mytoken1",
  "hash": "5e16b71e4aded06d1231d0b5ce2054475c6de39bf2f7d8f075836c42e67ce0a4",
  "validUntil": "2025-06-08T10:54:53.000Z",
  "role": "admin",
  "requestedBy": "rootUser",
  "issueDate": "2022-09-12T11:11:25.113Z",
  "lastUsed": "2022-09-12T11:11:25.113Z"
}

Status	Description	Response Content or Scheme
401	Access to resource is denied. User not authenticated (logged in) or session expired	`{ "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Unauthorized" ], "description": "Message of the error" } }`
403	User does not have enough permissions to access the resource	`{ "code": { "type": "string", "enum": [ "NOT_ALLOWED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Not allowed" ], "description": "Message of the error" } }`
404	Plugin is not enabled or not found	`{ "code": { "type": "string", "enum": [ "NOT_FOUND" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Plugin not found" ], "description": "Message of the error" } }`
409	Token with the same name already exists	`{ "code": { "type": "string", "enum": [ "INVALID" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Token with this name already exists" ], "description": "Message of the error" } }`
500	An internal server error has occured	`{ "code": { "type": "string", "enum": [ "SOMETHING_WRONG", "INTERNAL_ERROR" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "An internal server error occurred" ], "description": "Message of the error" } }`

Path: /api/tokens/{tokenHash}

Methods

GET

Returns information about a specific application token. Can be used only by an admin user

Parameters

Name	Location	Type	Required	Description
tokenHash	path	string	true	Hash of the token to get infos for

Responses

Status Description Response Content or Scheme

200

Information about a single specified token

{
  "name": {
    "type": "string",
    "description": "Human-readable name of the token. Must be unique. 30 characters max. Anything logner will be truncated"
  },
  "hash": {
    "type": "string",
    "description": "Hash of the token"
  },
  "validUntil": {
    "type": "string",
    "description": "Datetime when the token validity expires. ISO 8601 datetime string"
  },
  "role": {
    "type": "string",
    "description": "Access role which is provided by the token",
    "enum": [
      "admin",
      "editor",
      "viewer",
      "connectionManager",
      "monitoringViewer"
    ]
  },
  "requestedBy": {
    "type": "string",
    "description": "User who generated the token or null if token was not reuqested by a user"
  },
  "issueDate": {
    "type": "string",
    "description": "Datetime when the token was generated. ISO 8601 datetime string"
  },
  "lastUsed": {
    "type": "string",
    "description": "Datetime when the token was last used. ISO 8601 datetime string"
  }
} 

Example

{
  "name": "mytoken1",
  "hash": "5e16b71e4aded06d1231d0b5ce2054475c6de39bf2f7d8f075836c42e67ce0a4",
  "validUntil": "2025-06-08T10:54:53.000Z",
  "role": "admin",
  "requestedBy": "rootUser",
  "issueDate": "2022-09-12T11:11:25.113Z",
  "lastUsed": "2022-09-12T11:11:25.113Z"
}

Status	Description	Response Content or Scheme
401	Access to resource is denied. User not authenticated (logged in) or session expired	`{ "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Unauthorized" ], "description": "Message of the error" } }`
403	User does not have enough permissions to access the resource	`{ "code": { "type": "string", "enum": [ "NOT_ALLOWED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Not allowed" ], "description": "Message of the error" } }`
404	Plugin is not enabled or not found	`{ "code": { "type": "string", "enum": [ "NOT_FOUND" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Plugin not found" ], "description": "Message of the error" } }`
500	An internal server error has occured	`{ "code": { "type": "string", "enum": [ "SOMETHING_WRONG", "INTERNAL_ERROR" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "An internal server error occurred" ], "description": "Message of the error" } }`

DELETE

Deletes (and also revokes) the specified token and returns information about the remaining tokens in a list. Does nothing if the specified token was not found

Parameters

Name	Location	Type	Required	Description
tokenHash	path	string	true	Hash of the token to be deleted

Responses

Status Description Response Content or Scheme

200

List of objects describing the remaining tokens

{
  "name": {
    "type": "string",
    "description": "Human-readable name of the token. Must be unique. 30 characters max. Anything logner will be truncated"
  },
  "hash": {
    "type": "string",
    "description": "Hash of the token"
  },
  "validUntil": {
    "type": "string",
    "description": "Datetime when the token validity expires. ISO 8601 datetime string"
  },
  "role": {
    "type": "string",
    "description": "Access role which is provided by the token",
    "enum": [
      "admin",
      "editor",
      "viewer",
      "connectionManager",
      "monitoringViewer"
    ]
  },
  "requestedBy": {
    "type": "string",
    "description": "User who generated the token or null if token was not reuqested by a user"
  },
  "issueDate": {
    "type": "string",
    "description": "Datetime when the token was generated. ISO 8601 datetime string"
  },
  "lastUsed": {
    "type": "string",
    "description": "Datetime when the token was last used. ISO 8601 datetime string"
  }
} 

Example

{
  "name": "mytoken1",
  "hash": "5e16b71e4aded06d1231d0b5ce2054475c6de39bf2f7d8f075836c42e67ce0a4",
  "validUntil": "2025-06-08T10:54:53.000Z",
  "role": "admin",
  "requestedBy": "rootUser",
  "issueDate": "2022-09-12T11:11:25.113Z",
  "lastUsed": "2022-09-12T11:11:25.113Z"
}

Status	Description	Response Content or Scheme
401	Access to resource is denied. User not authenticated (logged in) or session expired	`{ "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Unauthorized" ], "description": "Message of the error" } }`
403	User does not have enough permissions to access the resource	`{ "code": { "type": "string", "enum": [ "NOT_ALLOWED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Not allowed" ], "description": "Message of the error" } }`
404	Plugin is not enabled or not found	`{ "code": { "type": "string", "enum": [ "NOT_FOUND" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Plugin not found" ], "description": "Message of the error" } }`
500	An internal server error has occured	`{ "code": { "type": "string", "enum": [ "SOMETHING_WRONG", "INTERNAL_ERROR" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "An internal server error occurred" ], "description": "Message of the error" } }`

Available API Paths​

Path: /api/tokens​

Methods​

GET​

POST​

Path: /api/tokens/{tokenHash}​

Methods​

GET​

DELETE​

Available API Paths

Path: /api/tokens

Methods

GET

POST

Path: /api/tokens/{tokenHash}

Methods

GET

DELETE