Restricted access tokens

A restricted access token lets you provide a token to an automation system or script without exposing all of your capabilities. It cannot grant more rights than you already have.

Role-based access control (RBAC) in MK.IO is controlled by granting permissions to users. Each permission is composed of:

A scope: defines the resources the permission applies to.
A role: defines what capabilities are granted on those resources.

For more details on RBAC in MK.IO, see Access, users and teams.

View your RBAC capabilities

Because a restricted access token cannot exceed your existing rights, the first step is to check what you have access to.

Log in to the MK.IO application at app.mk.io (opens in a new tab), then open api.mk.io/api/v1/user/rbac (opens in a new tab) in a second browser tab.

The response is a JSON document that describes your capabilities. If you have access to multiple organizations, switch to the correct organization first to see the right set of capabilities.

The teams field shows how your RBAC capabilities are derived. The rbac field is what you use when defining a restricted token.

{
  "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"
        ]
      }
    }
  }
}

This example shows capabilities on a single organization (core.customer) and a single project (core.project).

Create a restricted token

Send a POST request to the tokens endpoint with a permissions object that is a strict subset of the rbac object you received above.

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"
}
'

This request creates a token scoped to asset management on project 11111111-1111-1111-1111-111111111111 only. Requests using this token will be denied for any operation outside that scope.

If the request succeeds, the response includes the new token details and the JWT string.

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

Use the returned JWT for subsequent asset management operations.

API tokens Webhooks