- Concept
- Version · 6.0.2
- Manage
How access tokens work in Liquibase Secure
Last updated: November 17, 2026
Access tokens let Liquibase authenticate with Liquibase Secure server when nobody is signed in to the console. A personal access token belongs to a person and authenticates their own local Liquibase runs, such as running policy checks on their machine. A service token belongs to a service principal and authenticates a CI/CD pipeline. Knowing which kind to use, and what each one can reach, keeps a run from failing on a credential the server refuses.
Personal access tokens and service tokens
Both kinds of token go in the same Liquibase setting, liquibase.platform.apiKey, so a run uses one or the other, never both. They differ in who owns them and what they are allowed to do.
Personal access token | Service token | |
|---|---|---|
Belongs to | A person | A service principal |
Use it for | Local Liquibase runs, such as running checks with a policy assignment | CI/CD pipelines that send operation data to Liquibase Secure server |
Who creates it | The person it belongs to. Nobody can create one on someone else's behalf. | An administrator, when they create or rotate a service principal |
What it can reach | Whatever its owner can reach, with some exceptions | What its service principal is granted, such as sending operation data for the projects it is scoped to |
Expires | Yes, after 30, 60 or 90 days | No |
How many | Up to 10 active tokens per person | One active token per service principal |
Sends operation data | No | Yes |
Suspended when an administrator turns personal access tokens off | Yes | No |
To make one, create a personal access token for yourself, or create a service principal for a CI/CD pipeline to get a service token.
How a token is identified
Every token value starts with liq_. Token lists and the system log identify a token by its name and its prefix, which is liq_ followed by the next 6 characters of the value, for example liq_a1b2c3. The prefix lets you match a listed token to the value in your configuration without revealing the value.
The full value is shown once, when the token is created. Liquibase Secure server never shows it again. Lists, the system log and command output show only the name and prefix, and nobody can recover the value. If you lose a value, revoke the token and create a new one.
Token names
A personal access token needs a name of up to 32 characters. Spaces at the start and end are removed. Names do not have to be unique, but the console warns you when you reuse the name of one of your existing tokens, because unique names make token lists and the system log easier to read. A service principal's name, which its service token also carries, has the same 32-character limit.
Token statuses
A token has one of these statuses:
Status | What it means | What causes it |
|---|---|---|
active | The token works. | Creating the token, or turning personal access tokens back on for a suspended token |
expired | The token's expiry date has passed. It works up to the moment of its expiry date and is refused after it. | Reaching the end of the lifetime chosen when it was created |
revoked | The token never works again. | The owner or an administrator revoking it, the owner being deactivated or deleted, or its service principal being deleted |
suspended | The token is refused until the setting is turned back on. Only personal access tokens are suspended. | An administrator turning off personal access tokens for the workspace |
When more than one status applies, revoked wins over expired, and expired wins over suspended. A suspended token keeps counting down to its expiry date, so a token that reaches its expiry date while suspended is expired when the setting is turned back on. Tokens that stop working stay listed with their status, so they remain part of the record.
Lifetime and limits
When you create a personal access token, you choose a lifetime of 30, 60 or 90 days. The choices stop at the maximum lifetime your workspace allows, and the longest allowed choice is selected by default. The maximum is 90 days unless an administrator has lowered it to 60 or 30. Lowering the maximum does not shorten tokens that already exist. There is no option for a token that never expires.
Each person can have up to 10 active personal access tokens. Suspended tokens count toward this limit, and revoked and expired tokens do not. The limit is fixed, and administrators cannot change it. When you reach it, revoke a token you no longer use before you create another.
Any active member of the workspace can create personal access tokens for themselves, and no permission is needed. A token can do only what its owner can do, so someone with no group access can create one but cannot reach anything with it. Tokens are created and revoked only while you are signed in to the console. A personal access token cannot create or revoke tokens.
What a personal access token can do
A personal access token acts as its owner. Liquibase Secure server checks the owner's group access and permissions on every request, so a change to the owner's access applies to their tokens straight away.
A personal access token works for these local runs:
Running checks with a policy assignment: Liquibase fetches the assignment's policy configuration as the token's owner, so the owner needs access to the assignment. The assignment's owner or an administrator grants that access. To set up a run, follow Run checks with a policy assignment.
Fetching your workspace's license: A local run can get the license your workspace serves to Liquibase.
Reporting license usage: A local run can report which databases it ran against, for license tracking.
Liquibase Secure server refuses a personal access token for these, whatever its owner's permissions:
Sending operation data: A run that would report operations does not send them, and its exit code is unaffected. Use a service token in a pipeline to have its runs recorded.
Uploading files for an operation: This includes HTML reports.
Reading the license tracking report: The report covers the whole deployment's license usage, so reading it needs a service token. A personal access token gets
credential_type_mismatch.Managing access tokens: This covers creating and revoking tokens, and changing workspace settings.
Managing access: This covers groups, permissions, ownership, service principals and invitations.
Managing your account: This covers signing in to the console and changing your password or profile.
A personal access token is also refused by parts of Liquibase Secure server that do not check permissions on each request. Those include the rest of the policy features, such as policy catalogs, checks and packages.
A personal access token works only where Liquibase Secure server can be reached, so it never reaches beyond your own network boundary.
Errors when a token is refused
When Liquibase Secure server refuses a token, the response explains why. The response never contains the token's value. A token that is expired, revoked or suspended gets its error before any other check, so an expired token is reported as expired even on a request it could never have made.
HTTP status |
| Message | When it happens |
|---|---|---|---|
401 |
|
| The token's expiry date has passed. |
401 |
|
| The token was revoked. |
401 |
|
| Personal access tokens are turned off for the workspace. |
401 | None |
| The token is not recognized or is malformed, or its owner is deactivated or deleted. This error never names a token. |
403 |
|
| A personal access token was used for something it cannot do, such as sending operation data. |
403 |
|
| A service token was used for something it cannot do. |
403 | None | The usual permission error | The token's kind is allowed, but its owner does not have the permission. |
403 |
|
| Someone tried to create a token while personal access tokens are turned off. |
403 |
|
| Someone who is not a member of the workspace tried to create a token. |
400 |
|
| The lifetime asked for is longer than the workspace maximum. |
409 |
|
| The person already has 10 active personal access tokens. |
The 401 errors for an inactive token also carry token_name, token_prefix and workspace_name. An expired token adds expired_at, and a revoked token adds revoked_at and revocation_reason. The credential_type_mismatch error carries required_credential_type and supplied_credential_type, which name the kind of credential the request needed and the kind it got.
When Liquibase runs with a personal access token that is expired, revoked, or suspended, the command stops before it does any work and exits with code 1, so an update changes nothing. The error, LB-CMD-0072, or LB-CHK-0025 for a checks run that does not report operations, names the token and says why it stopped working. Error codes and exit codes lists the messages.
When a token's owner is deactivated
Deactivating a user revokes all of their personal access tokens at once, including suspended and expired ones. Reactivating the user restores their group access but not their tokens, so they create new ones. Their old tokens stay revoked and report token_revoked with the revocation reason owner_deactivated. Service tokens for service principals the user created keep working.
What happens to existing API keys when you upgrade
Before Liquibase Secure 6.0.2, each user could create API keys. Upgrading to 6.0.2 converts every key that belongs to a user into a personal access token. Its value stays the same, so local runs need no configuration change. Each converted token follows these rules:
It expires 90 days after the upgrade, or sooner if it was already set to expire earlier. Create a new personal access token before then.
It does not count toward the limit of 10 when it is converted. Someone with more than 10 keys keeps them all, but cannot create a new token until fewer than 10 are active.
It follows every other personal access token rule, so it can no longer send operation data.
Its prefix may be shorter,
liq_followed by 2 characters, because older keys stored less of the value.
Keys that belong to users who were already deactivated or deleted are revoked during the upgrade.
If a CI/CD pipeline sends operation data with a key that belonged to a user, its runs stop being recorded after the upgrade. Move the pipeline to a service token by creating a service principal for it.
Each converted key is recorded in the system log as Token converted to a personal access token. When the deployment has received operations sent with a user's key, liquibase-platform update lists an upgrade notice about the conversion and asks you to confirm it before it changes anything, as Upgrade Liquibase Secure server describes.