Personal access tokens

Personal access tokens can be an alternative to OAuth2 and used to:

  • Authenticate with the WVS API.
  • Authenticate with Git using HTTP Basic Authentication.

In both cases, you authenticate with a personal access token in place of your password.

Personal access tokens are:

note
Though required, WVS usernames are ignored when authenticating with a personal access token. For examples of how you can use a personal access token to authenticate with the API, see the API documentation.

Alternately, WVS administrators can use the API to create impersonation tokens. Use impersonation tokens to automate authentication as a specific user.

Create a personal access token

You can create as many personal access tokens as you like.

  1. In the top-right corner, select your avatar.
  2. Select Edit profile.
  3. On the left sidebar, select Access Tokens.
  4. Enter a name and optional expiry date for the token.
  5. Select the desired scopes.
  6. Select Create personal access token.

Save the personal access token somewhere safe. After you leave the page, you no longer have access to the token.

Prefill personal access token name and scopes

You can link directly to the Personal Access Token page and have the form prefilled with a name and list of scopes. To do this, you can append a name parameter and a list of comma-separated scopes to the URL. For example: 

https://wvs.example.io/-/profile/personal_access_tokens?name=Example+Access+token&scopes=api,read_user,read_registry
caution
Personal access tokens must be treated carefully. Read our token security considerations for guidance on managing personal access tokens (for example, setting a short expiry and using minimal scopes).

Revoke a personal access token

At any time, you can revoke a personal access token.

  1. In the top-right corner, select your avatar.
  2. Select Edit profile.
  3. On the left sidebar, select Access Tokens.
  4. In the Active personal access tokens area, next to the key, select Revoke.

View the last time a token was used

Token usage is updated once every 24 hours. It is updated each time the token is used to request API resources and the GraphQL API.

To view the last time a token was used:

  1. In the top-right corner, select your avatar.
  2. Select Edit profile.
  3. On the left sidebar, select Access Tokens.
  4. In the Active personal access tokens area, next to the key, view the Last Used date.

Personal access token scopes

A personal access token can perform actions based on the assigned scopes.

Scope Access
api Read-write for the complete API, including all groups and projects, the Container Registry, and the Package Registry.
read_user Read-only for endpoints under /users. Essentially, access to any of the GET requests in the Users API.
read_api Read-only for the complete API, including all groups and projects, the Container Registry, and the Package Registry.
read_repository Read-only (pull) for the repository through git clone.
write_repository Read-write (pull, push) for the repository through git clone.
read_registry Read-only (pull) for Container Registry images if a project is private and authorization is required. Available only when the Container Registry is enabled.
write_registry Read-write (push) for Container Registry images if a project is private and authorization is required. Available only when the Container Registry is enabled.
sudo API actions as any user in the system (if the authenticated user is an administrator).

When personal access tokens expire

Personal access tokens expire on the date you define, at midnight UTC.

  • WVS runs a check at 01:00 AM UTC every day to identify personal access tokens that expire in the next seven days. The owners of these tokens are notified by email.
  • WVS runs a check at 02:00 AM UTC every day to identify personal access tokens that expire on the current date. The owners of these tokens are notified by email.

Troubleshooting

For additional support, please reach out to us on our Discord or By Email.