gitlab API error: 401 Unauthorized on deploy token with the wrong scope

TL;DR

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

Error

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/pstCBvTuD5C59oi_6bm87CdA