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 the Access control section of 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 Administration > Access control > API tokens. 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 Principals, grants it roles and issues its tokens on its profile.

Creating a token​

A personal token:

  1. Open Administration > Access control > API tokens 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 Principals - 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 gets that in the same step as its token: when an administrator creates the token on the account's profile, May call request-response services lists the scenarios to choose from, and the account is given a role granting Scenario.Invoke on exactly those. The choice belongs to the account, not to the token - every token of the account calls the scenarios chosen last, and choosing none takes the role away - and it is recorded in the audit log like a role edited by hand. The screen shown after creating the token says which scenarios it can call. 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 finds or creates a service account for the server (mcp-<server>), a role granting MCP.Use on exactly that server, binds them 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 and the role are ordinary objects in Access control, so the token is revoked and the role reviewed like any other.

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 removing the role, cuts the client off within 30 seconds. 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 API tokens, a service account's on the account's profile. Deactivating the owner or removing its role bindings cuts the token off as well. Each of these takes effect within 30 seconds on every Designer instance.

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 API tokens in the Designer configuration.