Skip to main content
Version: 3.0

Personal Access Tokens

Let a script or another system call the API as you, limited to the scopes you choose, without using your password.

Create in
Profile › Security
Expiry
30, 90 (default) or 180 days, or 1 year
Scopes
Chosen per workspace

Personal Access Tokens (PATs) let you authenticate with the MaestroHub API without using your password. They are ideal for publishing data to UNS topics from external systems, querying pipeline execution results, integrating with SCADA/MES/ERP platforms, and any scenario where you need programmatic access to the platform.

Personal Access Tokens are managed from your profile's Security tab. To get there:

Step 1: Open your profile. Click your avatar at the bottom of the left sidebar and choose Profile Settings.

The account menu, opened from the avatar at the bottom of the sidebar, with Profile Settings markedThe account menu, opened from the avatar at the bottom of the sidebar, with Profile Settings marked

Step 2: Go to the Security tab. On the Profile Settings page, select the Security tab. The bottom section of this tab displays your Personal Access Tokens list along with a Create Token button.

Profile Settings page showing the Security tab with the Personal Access Tokens section and Create Token buttonProfile Settings page showing the Security tab with the Personal Access Tokens section and Create Token button

Token List​

The token table shows all tokens you have created, including active, expired, and revoked ones.

ColumnDescription
NameThe descriptive name you assigned to the token.
ScopesColor-coded badges showing the permissions granted to the token, grouped by feature area.
CreatedThe date the token was created.
Last UsedThe date the token was last used for authentication, or "Never" if it has not been used.
ExpiresThe expiration date of the token.
StatusCurrent state: Active, Expired, or Revoked.

Creating a Token​

You create a token while signed in to MaestroHub. A request made with a personal access token, an API client or an agent cannot create one, and neither can an administrator impersonating you: the API answers 403.

  1. On the Security tab, click the Create Token button in the Personal Access Tokens section.

  2. Enter a Token Name (max 255 characters). Use a descriptive name that identifies the purpose: for example, "ERP Data Sync" or "UNS Topic Publisher".

  3. Select an Expiration period from the dropdown: 30 days, 90 days (default), 180 days, or 1 year.

  4. Choose the Workspaces the token is for. It starts with the workspace you are in; add others with Add workspace. The token works only in the workspaces listed.

  5. If RBAC is enabled, select the Permissions for each workspace: click a workspace to edit its list. Your role differs by workspace, so each one offers what your role allows there and keeps its own selection. Scopes are organized by group (Pipelines, Connectors, Functions, UNS, Dashboards, Apps, Audit Log and more; the full list is under Available Scopes). You can toggle individual permissions or click a group name to select all scopes in that group. The buttons above the list fill it in for you:

    • Select all: every scope offered.
    • Read-only: every Read scope offered.
    • Build apps: the scopes an AI assistant needs to build App Studio apps (App Studio is in release 3.0 as Beta, a paid add-on) over MCP (apps:write, uns:read, pipelines:read, connectors:read, entities:read). The button is disabled when your role lacks one of them; hover it to see which.
    • Clear: removes every selection.

    A counter in the top-right corner shows how many permissions are currently selected.

  6. Click Create Token.

Create Personal Access Token dialog with token name, expiration dropdown, the Workspaces field, the shortcut buttons, and permission scope selection grouped by feature areaCreate Personal Access Token dialog with token name, expiration dropdown, the Workspaces field, the shortcut buttons, and permission scope selection grouped by feature area

After the token is created, MaestroHub displays the generated access token in a copyable text field.

Important

The token value is displayed only once. Copy it immediately and store it in a secure location. Once you close this dialog, the token cannot be retrieved again; you would need to create a new one.

Scopes​

When RBAC is enabled, you assign permissions to a token per workspace. You can only grant scopes your own account has in that workspace; the selector shows your role there. A token never does more than its list for a workspace allows, and never more than your role there allows.

A token created before permissions were per workspace has a single list. It keeps working as before: that list applies in every workspace you belong to, and the token list shows it as All workspaces.

For the full list of available scopes, see Available Scopes.

info

When RBAC is not enabled, tokens are created without scope restrictions; they inherit the full access level of your account. An informational banner on the creation form indicates this.

Using a Token​

Include the token in the Authorization header of your HTTP requests:

curl -H "Authorization: Bearer <your-token>" \
  -H "X-Workspace-ID: <your-workspace-id>" \
  https://your-instance.example.com/api/v1/engine/pipelines

The platform validates the token on every request by checking:

  1. Signature: The JWT signature is verified against the server's signing key.
  2. Expiration: The token must not be past its expiry time.
  3. Revocation: The token must not have been revoked.
  4. Workspace: The request's workspace must be one the token names, and you must still belong to it. A token for a single workspace does not need the X-Workspace-ID header.
  5. Scopes: The requested action must be covered by the token's scopes for that workspace (when RBAC is enabled).

Revoking a Token​

To revoke a token, click the Revoke action on the token row and confirm in the dialog.

  • Revocation is immediate: any application using the token loses access right away.
  • Revocation is permanent: a revoked token cannot be reactivated. Create a new token if needed.
  • Revoked tokens remain visible in your token list with a Revoked status badge.

Limits and Constraints​

ConstraintValue
Maximum active tokens per user50
Maximum token name length255 characters
Maximum token lifetime1 year (365 days)