Manage Scoped Access Tokens

For Access Tokens, you can:

Create a token for API and CLI access.
Revoke or delete a token you no longer need.
Configure its version control access and environment variables.

Create a Scoped Access Token

Prerequisites

The group admin or organization admin role

Steps

1. Open the access tokens

Select the group or organization in the Explorer, then open its Access Tokens tab.

2. Create the token

Open the dialog with Create Access Token and set a name and an expiration date.

Admin Role Assignment decides the token's role: with it the token acts as admin of its scope, without it as a normal user.

Copy the token now

Copy and store the access token in a secure location. You will not be able to view the token again after you leave or refresh the page.

For a token that acts with your own permissions instead of a technical user's, see Manage Personal Access Tokens.

Revoke or delete Scoped Access Tokens

Prerequisites

An existing token in the group or the organization
The group admin or organization admin role

Steps

1. Open the access tokens

Select the group or organization in the Explorer, then open its Access Tokens tab.

2. Revoke or delete the token

Both actions sit directly in the token's row:

Revoke: the slider. This disables the token.
Delete: the trashcan icon. Note that once a token is deleted, it cannot be recovered.

Token Settings

A token carries two settings, named Environment Variables and Version Control Access . They apply to the sessions started with that token.

Your user profile carries those settings too. They apply to the sessions you start yourself: Environment variables and SSH Key Setup.

Version Control Access

In the Version Control Access tab, you can add an access token for a specific project in your version control system.

Prerequisites

An existing access token in vHaaS
A project or group access token in your version control system

Steps

1. Add the access token

Use Add Access and fill in the dialog for the project or group that the registered runner needs to access.

Do not use a personal access token of your version control system here

Create a dedicated project or group access token in your version control system instead. The token registers a GitLab runner in the given group or project, which only works if it carries the necessary permissions there.

A personal access token of your version control system is used for SSH Key Setup in the user profile.

Environment Variables

In the Environment Variables tab, you can add environment variables that will be set at the beginning of a session on the VM. These variables can be used to configure the environment for your application.

Prerequisites

An existing access token in vHaaS

Steps

1. Add the variable

Use Add Variable and set a name and value.

Troubleshooting

Symptom	Likely cause	Solution
API or CLI request fails with `401`	No valid token was sent — the `private-token` header is missing, or `VEHAAS_TOKEN` is not set	Set `VEHAAS_TOKEN` or pass `--token`; see REST API Authentication.
Requests fail with `401` although the token is still listed in the table	The token has expired or was revoked. Note that the Status column shows Revoked for expired tokens too, and that revoking cannot be undone	Compare Status against the expiration date and create a new token; an expired or revoked token can never be reactivated.
Requests keep succeeding for up to a minute after the expiration date has passed	Token lookups are cached briefly, and expiry is only re-evaluated once the cache entry ages out	Wait a moment. Revoking or deleting a token through the UI takes effect immediately.
Actions are attributed to your own account although you passed a token	A bearer JWT takes precedence: if the request also carries a Web UI session, the `private-token` header is ignored	Send the token from a clean client that has no browser session.
The token value is no longer visible anywhere	The value is shown only once, in the dialog directly after creation	Create a new token and store the value in a secure location.
Create Access Token is not available	Group-level tokens require the Group Admin role, organization-level tokens the Organization Admin role	Ask an admin of the respective scope to create the token.
The expiration date jumps back when you pick an earlier one	The dialog enforces a minimum lifetime and resets shorter values to the default of 14 days	Choose a date at least 14 days in the future.
The role or expiration date of an existing token cannot be edited, and its technical user cannot be added to a group	Name, scope, role and expiration date are fixed at creation time; vHaaS rejects both operations, and the technical user's group membership comes from the token. The only later change is revoking	Create a replacement token with the required scope and role, then delete the old one. Everything else — version control access, environment variables, cleanup paths — is configured on the technical user itself.
After deleting a group- or organization-level token, its sessions lose their actor	Deleting the token also deletes the backing technical user	Revoke instead of delete when you still need the history.
GitLab runner registration fails although the vHaaS token works	The token stored under Version Control Access has the wrong role or scope	Project-level registration needs a `Maintainer` token with `api` scope, group-level an `Owner` token with `api` scope — see Starting a GitLab Runner.
The runner registers in the wrong GitLab project, and the ID cannot be corrected	The Project/Group ID of an existing version control access is immutable	Delete the entry and add a new one with the correct Provider URL and ID.
Environment variables are missing in a session started through a token	Variables are taken from the user the session belongs to, so only the technical user's variables apply	Define the variables on the token itself, in its Environment Variables tab.
A variable name is rejected	Windows system variables such as `PATH`,`SYSTEMROOT`,`WINDIR`,`COMSPEC`,`HOMEPATH`,`HOMEDRIVE`,`USERPROFILE`,`APPDATA`,`LOCALAPPDATA`,`PROGRAMFILES`,`PROGRAMFILES(X86)`,`TEMP`, `TMP`, `ALLUSERSPROFILE` are blocked,	Choose a different name.
A variable does not appear as an environment variable on the VM	Variables that carry a file path are written as a path entry, not as an environment variable	Leave the path field empty for a plain environment variable.
Environment variables are gone after the session ended	All variables are unset during cleanup — this is by design	Nothing to do; they are set again at the start of the next session.
A user you do not recognize holds a session or appears in the assembly calendar	The session was booked with a group- or organization-level token, so its technical user is the actor. It is shown as `Bot: <token name>`	You do not need to track down the token's owner: any member of the token's group or organization who can view the assembly may end or take over that session. To find the token, look for `<token name>` in the Access Tokens tab — of the group for a group-level token, of the organization for an organization-level one.
As group admin you see the technical user in a session but cannot open or manage it	Technical users of organization-level tokens are only manageable by organization admins; a group admin manages only the technical users of their own group's tokens	Ask an organization admin, or use a group-level token instead.
The technical user cannot reach an assembly that you can reach	A group-level token's technical user belongs to exactly that one group, plus the organization as a normal member — not to your other groups	Move the assembly into the token's group, make it public in the organization, or create the token in the group that owns the assembly.