Skip to main content
Version: Current

API tokens

A Nussknacker API token is the credential for anything that is not a person at a browser: nu-cli, a script, a CI pipeline, an integration. It is a string starting with nuk_, shown once when it is created and never again, and it signs its owner in without a password. Every request made with it acts with the roles its owner holds at that moment - a token grants nothing of its own - so it expires, can be revoked and is listed with when it was last used.

Tokens come with access control in the Designer; an installation without it issues none.

Who can have a token​

  • A local user (an account with a password kept by Nussknacker) creates personal tokens under My API tokens in the user menu. Such a token does what you can do.
  • A person who signs in through an identity provider (OpenID Connect, OAuth2) cannot have personal tokens - the page says so - because their access is read from each sign-in, not kept in Nussknacker. Ask an administrator for a service account and a token issued to it.
  • A service account is an account meant for a machine client: it has no password and signs in only with its tokens. An administrator creates it under Administration → Service accounts, assigns it roles and issues its tokens on its profile.

Creating a token​

A personal token:

  1. Open My API tokens in the user menu and click Create token.
  2. Name it after where it will be used (CI pipeline, laptop nu-cli), so that it can be told apart and revoked later.
  3. Set its Lifetime in days, or leave it empty for the installation's default (90 days unless the administrator changed it). The installation also sets the longest lifetime a token may have; only where it sets none can a token be created that never expires, and revoking is then the only way to end it.
  4. Click Create. The token is shown once, with a summary of what it will be able to do - Copy token and put it where the client reads it from. A token you did not save cannot be recovered: revoke it and create another.

A service account's token is created the same way by an administrator on the account's profile under Service accounts - it needs the RBAC.Manage action - and is shown once there.

Using a token​

Send the token in the Authorization header of requests to the Designer's API:

curl -H "Authorization: Bearer nuk_..." https://<designer>/api/user

A client that cannot set Authorization sends it in the X-Nussknacker-Api-Token header instead; that header is read only when no Authorization header arrives.

nu-cli​

Signing nu-cli in with a token is the preferred way, and the only one that works unattended. Name the Designer and pass the token from a file or a pipe, so that it never shows up in your shell history:

nu-cli login --url https://<designer> --token-stdin < token.txt
pbpaste | nu-cli login --url https://<designer> --token-stdin # from the clipboard
nu-cli whoami # checks the stored credential

nu-cli login --url https://<designer> without a token flag opens a hidden prompt to paste the token into. In CI and in scripts skip login altogether and set NU_URL and NU_TOKEN in the environment.

Signing in through the browser (nu-cli login --browser) is the second choice: it needs a person at a browser and reuses that person's session, so it fits a one-off job on your own machine, not a server or a pipeline. People signing in through an identity provider use a service account's token on servers and in pipelines, as above.

Calling request-response scenarios​

A deployed request-response scenario whose Access is Nussknacker API token required (see Who may call the scenario) is called with a token whose owner may call it - the Scenario.Invoke action on the scenario or its category:

curl -X POST -H "Authorization: Bearer nuk_..." -H "Content-Type: application/json" \
-d '{"customerId": "42"}' https://<designer>/scenario/<slug>

A personal token calls the scenarios its owner may call. A service account's token calls the scenarios the account may call: those its roles grant by category, and those it holds as direct access with Scenario.Invoke, set under Direct access on the account's page. The choice belongs to the account, not to the token - every token of the account calls the same scenarios, and a change of the direct access changes what every one of them calls. The token window says what the token will be able to call before it is issued. A token generated for an MCP server may call the scenarios behind the server's tools.

Tokens for MCP clients​

An MCP server published by the Designer is called with a Nussknacker API token whose owner holds MCP.Use on that server; nothing else is accepted. You do not have to set that up by hand: Generate token on the server's page in the MCP tab creates the server's own service account the first time (named mcp-<server>, found by the server, not by the name), gives it MCP.Use on the server and Scenario.Invoke on the scenarios behind its tools, and issues a token shown once. Clicking it again issues another token for the same account, and the page lists the server's tokens. It needs the RBAC.Manage action. The account's access follows the server from then on: saving the server with other tools changes the scenarios it may call, and deleting the server deactivates the account and revokes its tokens. It cannot be given roles or other access by hand. While the account is deactivated, no token is issued for the server; reactivate the account under Service accounts to issue them again.

The MCP client sends the token in Authorization: Bearer, in X-Nussknacker-Api-Token, or in a header the server names itself (Token header in the token options, e.g. X-Api-Key) when it cannot set Authorization. Revoking the token, or deleting the server, cuts the client off within 30 seconds with the default settings. A server may instead be set to Open - no token required in its options, where the installation allows it: anybody who reaches it can then call its tools, attributed to nobody.

What a token cannot do​

A token is for working with scenarios and the Designer's API. Whoever holds it, it cannot:

  • manage access - create tokens, change roles or bindings, create or deactivate principals; the only exceptions are listing its owner's tokens and revoking itself;
  • use the APIs of the Designer's extensions - Access control, MCP management, the Configurator, Topics - which answer it with 403;
  • act as another user (impersonate);
  • read the installation's configuration endpoint, which holds credentials.

Lifetime, revocation and audit​

A token ends when it expires or when it is revoked: a personal token under My API tokens, a service account's on the account's profile. Deactivating the owner cuts the token off as well; taking away some of the owner's roles and direct access narrows what the token may do, and taking all of them away cuts it off too. Each of these takes effect within 30 seconds on every Designer instance with the default settings.

The token list shows each token's status (Active, Expired, Revoked), when it was created and when it was last used. Issuing and revoking a token are recorded in the Access control audit log, and what a token did to a scenario is recorded in the scenario's activities with the token's id next to its owner, so two tokens of one owner stay apart.

An installation's defaults - the default and the longest lifetime, and how long the authorization data may go stale before tokens are refused - are set by its administrator; see Access control in the Designer configuration.