## TL;DR

GitLab 401s because the deploy token lacks the scope for the operation: grant the token the right scope (read_registry, write_repository, etc.) or use a token type that fits.

## Error

```text
401 Unauthorized on deploy token with the wrong scope
```

## Steps

1. Check the token's scopes in the project settings Expected: you see what it has.
2. Grant the missing scope for the operation Expected: the token is capable.
3. Retry the operation Expected: it succeeds.
4. Document the required scopes for the automation Expected: future tokens are right first time.

## When to use

- 401 on GitLab deploy token
- The scope is wrong

## When not to use

- The token is expired or revoked (then the error is the same; check)
- The token belongs to another project (then check the project)

## Tool compatibility

- GitLab deploy tokens
- CI/CD integrations

## Variant phrasings

### gitlab deploy token 401

The scope is wrong. Grant what the operation needs.

### deploy token unauthorized scope

Same: check scopes in project settings.

## Why it happens

Deploy tokens are narrowly scoped by design, and agents assume the token they were given can do everything.

## Edge cases

- Project vs group deploy tokens have different visibility
- Rotate deploy tokens on a schedule

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_CBvTu_D5C59oi_6bm87CdA