Skip to content
Craftifact

Create a robot account and use its token

How to declare a robot account in the Control Plane, use it as an owner in Craftifact, and send the token correctly.

Quick path

  1. Open the Control Plane and go to the target instance.
  2. In Effective configuration, add a new entry under robot_accounts with id, owners, roles, and optional token_policy.
  3. Save the change and use Deploy Config so the robot account becomes part of the active instance configuration.
  4. Then sign in to Craftifact with a user that is listed under owners for that robot account.
  5. In Craftifact, open the Robot accounts tab in the main explorer navigation between Browse and Dependencies.
  6. Select the robot account, choose the lifetime and required package scopes, then generate the token.
  7. Store the token in the calling tool and send it as a bearer token or via basic auth.

Example in the instance configuration

robot_accounts:
  - id: acceptance-test
    description: A robot for executing the acceptance test.
    owners:
      - some.developer@example.com
    roles:
      - a-defined-role-with-necessary-privileges
    token_policy:
      default_ttl_days: 30
      allow_infinite_ttl: false
    enabled: true

Important parts of this example:

  • owners defines which users are allowed to mint tokens for this robot account.
  • roles defines the permissions the robot will have in Craftifact.
  • token_policy defines default and maximum token lifetime behavior for that robot account.

If you reference owners by email address, that user must later exist on the instance.

What happens in Craftifact

After the config is deployed, the robot account becomes visible in Craftifact for its owners in the Robot accounts tab. Users without permission to manage robot accounts do not see that tab at all.

The tab uses a two-pane layout:

  • The left side lists the robot accounts you own.
  • The right side shows the currently selected robot account with owners, granted roles, token status, TTL controls, scope toggles, and token actions.

The list is filterable by robot ID and description. Filtering is applied before paging, and paging is fixed to 8 visible rows.

In that tab the owner can:

  • generate a token with the required lifetime,
  • select package scopes, including quick toggles for all scopes or no scopes,
  • revoke and regenerate an existing token.

The generated token is shown once only and copied to the clipboard automatically. Generating a new token revokes the previous one. Infinite TTL remains available only when the robot account policy allows it.

Rationale: why the token is issued in Craftifact
In the Control Plane, the administrator sets the guardrails: which robot account exists, who may use it as an owner, which roles it has, and which token lifetimes are allowed. Actual usage is then delegated to those owners, in practice often developers. They can configure, issue, and renew the token in Craftifact within those limits whenever they need it, without involving the administrator in the Control Plane each time.

Reading the robot account details

The detail pane is meant to answer three questions without another config lookup:

  • Which owners may use this robot account
  • Which roles and effective permissions it has
  • Which token limits apply right now

On wider screens, token settings, token actions, and account details are shown side by side. Roles are grouped into readable summaries so owners can check the effective permission shape before minting a token.

Using the token

For requests against Craftifact, you can send the token in two ways:

  1. As a bearer token in the Authorization: Bearer <token> header.
  2. Via basic auth with the token as the password.

For basic auth, the username can be either the robot ID or the placeholder __token__. Using the robot ID is preferable, for example acceptance-test, because it makes the consuming integration easier to identify later without decoding the token first. __token__ also works, but it is less descriptive.

Basic auth example:

Username: acceptance-test
Password: <token>

Common failure cases

  • The robot account was saved, but the current configuration has not been deployed yet.
  • The user is not listed as an owner or does not exist on the instance yet.
  • The robot account roles do not include the permissions required for the later access.
  • A new token was generated, but the integration still uses the revoked previous token.
  • The Robot accounts tab is missing because the signed-in user does not have permission to manage robot accounts on that instance.