Role-based Access Control (RBAC) in MK.IO is controlled by granting permissions to users. Permissions are composed of:

• a scope: defines the resources that this right applies to, and
• a role: defines what capabilities are granted on those resources.

For more details on RBAC in MK.IO, please visit this article.

A restricted access token is useful when you want to provide a token to an automation system, or to some script, without exposing all of your capabilities.

Listing your RBAC capabilities

A restricted access token cannot grant more rights than you have already, so the first step in defining such a token is to take a look at what you have access to.

Log into the MK.IO application at app.mk.io and then open api.mk.io/api/v1/user/rbac in a second tab in your browser.

You should receive a JSON document which describes your capabilities. You may have different capabilities on different organizations, if so you will need to "Switch Organization" to see the correct set of capabilities.

The teams information here is useful for seeing how your RBAC capabilities are being generated, but it is the rbac section itself that we are interested in here.

{
  "rbac": {
    "core.customer": {
      "00000000-0000-0000-0000-000000000000": {
        "core.customer": [
          "get",
          "update"
        ],
        "core.invite": [
          "create",
          "delete",
          "get",
          "update"
        ],
        "core.project": [
          "assign",
          "create",
          "delete",
          "get",
          "update"
        ]
      }
    },
    "core.project": {
      "11111111-1111-1111-1111-111111111111": {
        "ams.asset": [
          "create",
          "delete",
          "get",
          "update"
        ],
        "ams.assetfilter": [
          "create",
          "delete",
          "get",
          "update"
        ]
      }
    }
  }
}

Here we can see that you have certain capabilities on a single organization (referenced as core.customer in this sample) and on a single project.

Defining your restricted token

curl --request POST \
     --url https://api.mk.io/api/v1/user/tokens \
     --header 'accept: application/json' \
     --header 'authorization: Bearer bearer-token' \
     --header 'content-type: application/json' \
     --data '
{
  "permissions": {
    "core.project": {
      "11111111-1111-1111-1111-111111111111": {
        "ams.asset": [
          "create",
          "delete",
          "get",
          "update"
        ]
      }
    }
  },
  "type": "restricted",
  "description": "Restricted token for automation",
  "expireDate": "2025-08-22T10:15:00.000Z",
  "organizationId": "00000000-0000-0000-0000-000000000000"
}
'

Here we can see a request to create a token which allows only the use of my asset capabilities for the 11111111-1111-1111-1111-111111111111 project. The permissions dictionary in the request a strict subset of the rbac dictionary I received earlier.

If the request is successful then the response will include the details of the new token, including the JWT string.

{
  "metadata": {
    "id": "00000000-0000-0000-0000-000000000000",
    "type": "restricted",
    "JWT": "eyJ..."
  },
  "spec": {
    ...
    ...
  }
}

The returned JWT token can then be used for subsequent asset management operation and will be denied permission for operation outside of asset management.