Skip to main content
Version: Mosquitto 2.7

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

Available API Paths


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

NameLocationTypeRequiredDescription
tokenHashpathstringtrueHash 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

NameLocationTypeRequiredDescription
tokenHashpathstringtrueHash 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"
}
}