Access tokens

pixmoat has two kinds of token. Your CI uses a project access token. Scripts and AI agents that act as you use a personal access token. Both go in an Authorization: Bearer <token> header, and the Playwright client reads the token from PIXMOAT_TOKEN.

	Project access token	Personal access token
Starts with	`pxg_`	`pxgp_`
Belongs to	One project	You, in every organization you belong to
Created in	The project’s Settings → Tokens	Account → Personal Access Tokens
Who can create one	Project admins	Any signed-in user
Can do	Upload screenshots, read results and, if allowed, record review decisions for its project	Whatever your role allows in each project
Expires	Never	On the date you choose, or never (see Expire a token)

pixmoat shows a token only once, when you create it. It stores a hash, so nobody can show it to you again. If you lose a token, revoke it and create a new one.

Create a project access token

You need to be a project admin: an organization owner or admin, or a member with the Admin role on the project (see Team and roles).

Open the project, select Settings in the sidebar, then the Tokens tab.
Select Create token and enter a Token name, such as GitLab CI. Create one token per pipeline, so you can revoke one without breaking the others.
Leave Allow review decisions unchecked for a capture pipeline. Check it only when CI or an agent must approve or reject screenshots with this token. An upload-only token that leaks can’t approve its own changes.
Select Create. You’ll see “Copy this token now. You won’t be able to see it again.” Select Copy, then Dismiss.

Store the token as a masked CI/CD variable named PIXMOAT_TOKEN. Never commit it to the repository, .pixmoat.yaml or a build artifact. GitLab CI and GitHub Actions show where the variable goes.

The Tokens list shows each token’s name, when it was created, Last used once it has authenticated a request, and its scopes: UPLOAD, plus REVIEW when Allow review decisions was checked.

Create a personal access token

Open the user menu in the top right and select Account.
Under Personal Access Tokens, select Create token.
Enter a Token name, such as Release script.
Select Create, then Copy the token.

A personal access token has no scopes of its own. It acts as you, with your role in each organization and project, so treat it like your password. Store it in your CI secret store or your agent host’s environment, never in a file you commit.

The project’s Settings → Agent tab also has Create a token for this. That creates a personal access token named after the project, with no expiry.

Expire a token

Project access tokens don’t expire. Rotate them on a schedule instead (see Rotate a token).

Personal access tokens have an Expiration (optional) field. Choosing a date there currently makes Create fail, so leave it empty. A token without a date never expires. Revoke it when you no longer need it.

Rotate a token

There’s no rotate button. To rotate a token without breaking CI:

Create a new token with the same access as the old one. For a project access token, match the Allow review decisions setting.
Replace the PIXMOAT_TOKEN value in your CI/CD variables or secret store.
Run a pipeline. The new token shows a Last used date in the list.
Revoke the old token.

Rotate right away if a token was printed in a log, pasted into a ticket or committed, even to a private repository.

Revoke a token

Project access token: in Settings → Tokens, select Revoke next to the token. The token stays in the list marked Revoked.
Personal access token: on Account, select Revoke next to the token. It disappears from the list.

Revoke takes effect at once and doesn’t ask for confirmation. Any pipeline or agent that still uses the token fails with 401 on its next request.

Some account actions also revoke your personal access tokens:

Secure account revokes them unless you clear Revoke my personal access tokens.
Resetting a forgotten password always revokes them.

Neither touches project access tokens. See Devices and security.

Which token each operation needs

“Project user” and “project admin” mean your effective access to the project. Organization owners and admins are project admins on every project. Members get the role they were granted per project (see Team and roles).

Operation	Project access token	Personal access token
Start a build, upload screenshots, finish the build (the Playwright client)	Yes	Project user or admin
Read build results and the build summary (a CI gate)	Yes	Project user or admin
Approve or reject screenshots, finish a review through the API	Only with Allow review decisions	Project user or admin
List your organizations and projects	No	Yes
Promote a build by hand (Manual promotion)	No	Project admin
Change project settings, including the Git provider	No	Project admin
Create or revoke project access tokens	No	Project admin
Create or revoke personal access tokens	No	Yes
Change your password, sign out devices, secure your account	No	No. Sign in in a browser.

Decisions recorded with a token count as agent decisions, not human approvals. A project’s approval policy still needs a person to approve. See Why an agent’s approval doesn’t count.

When a token is rejected

Response	Why	What to do
`401` `invalid or expired token`	The token is mistyped, revoked or expired. A project access token also gets this for any project other than its own, so check `PIXMOAT_PROJECT` too.	Compare the project slug with the project’s URL. If it matches, create a new token and update the variable.
`401` `missing authorization header` or `malformed authorization header`	The request had no token, or the header isn’t `Bearer <token>`.	Set `PIXMOAT_TOKEN`. For your own scripts, send `Authorization: Bearer <token>`.
`401` `authentication required`	A project access token was used for something only a personal access token or a signed-in user can do.	Use a personal access token. See the table above.
`403` `insufficient token scope`	A project access token without Allow review decisions tried to record a decision.	Create a token with Allow review decisions checked, or decide in the app.
`403` `insufficient access`, or `404` for a project you know exists	Your personal access token works, but you have no access to that project, or too little.	Ask a project admin to grant you access.

Approver tokens

A project admin can grant a project token the approve scope together with review. Its current approval counts as one approver toward min_approvals. Revoking the token or removing the scope stops its approval counting. Approver tokens do not satisfy required roles, distinct-author rules or CODEOWNERS approval.

Before an automated review, read GET /api/projects/{slug}/agent-review-policy?branch={branch} to check whether the credential counts as an approver and which settings block agent-only completion. Hosted OAuth connections use a PAT identity and do not count as approver tokens.