## TL;DR

GitLab auth failures are almost always a token without the right scope or a token passed in a way the tool does not read. Confirm the token has API read scope, point at the right GitLab host, and pass it through the tool's documented auth flag.

## Error

```text
"trufflehog gitlab: authentication failed"
```

## Steps

1. Verify the token works at all: call the GitLab API with it from the same machine. Expected: a 200, proving the token and network are fine.
2. Check the token scope: scanning needs API read access to the groups or projects. Expected: scope covers what you scan.
3. Confirm the GitLab host: self-managed instances need the explicit base URL, not the default. Expected: the tool targets the right host.
4. Pass the token through the tool's auth flag exactly as documented, without extra quoting or shell interpolation issues. Expected: the tool authenticates.
5. Retry a small scope first (one project), then widen. Expected: quick confirmation before the big scan.

## When to use

- Trufflehog GitLab scans fail with authentication errors.
- After token rotations or GitLab upgrades.

## When not to use

- GitHub scan auth (different token type).
- Rate limiting (different error).

## Tool compatibility

- Trufflehog v3 GitLab source; GitLab SaaS and self-managed.

## Variant phrasings

### trufflehog gitlab 401

Same auth cause.

### trufflehog cannot list gitlab projects

Often auth, sometimes scope.

## Why it happens

Tokens lose scope on rotation, self-managed URLs get misconfigured, and shell quoting mangles tokens with special characters.

## Edge cases

- Expired tokens fail the same way as wrong tokens; check expiry.
- Group tokens cannot see projects outside the group; use a token with the right reach.
- Tokens in CI logs get revoked by secret scanning; pass them masked.

## Provenance

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