Personal Access Tokens#

Personal Access Tokens (PATs) authenticate non-interactive clients — CI/CD pipelines, the DevGuard scanner, and API scripts — against DevGuard. DevGuard supports two token types with different security properties. Use asymmetric request signing whenever possible.

Token Types#

Asymmetric Token (ECDSA Request Signing)#

The asymmetric PAT uses public-key cryptography so the private key never leaves the machine that created it.

1. Generate an ECDSA P-256 key pair client-side (browser or CLI).
2. Register only the public key with DevGuard. The private key is shown once and never transmitted to or stored by the server.
3. Sign every API request with the private key. The signature covers the HTTP method and a SHA-256 digest of the full request body.
4. DevGuard verifies the signature using the stored public key, looked up via a fingerprint header.

Security properties:

• No secret on the wire — only a signature travels; the private key never leaves your environment
• Request integrity — the full body is included in the signature; tampering invalidates it
• Replay protection — captured requests are useless without the matching private key
• Server compromise safe — even if the DevGuard database were exfiltrated, no private keys could be extracted

Symmetric Bearer Token#

A symmetric PAT is an opaque secret prefixed with dvg_ generated server-side and shown to you once. Send it as an Authorization: Bearer <token> header. DevGuard stores only a SHA-256 hash — the cleartext is never persisted.

Security properties:

• Zero server-side cleartext — only the hash is stored; database leaks do not expose the token
• Simpler integration — no signing library required; any HTTP client works
• Higher interception risk — a captured token can be replayed until it expires, unlike a per-request signature

Both token types provide access to the same API actions. Choose based on the security requirements and tooling constraints of your environment.

Scopes#

Every token is created with one or more scopes that limit what it can do:

Both scopes can be combined on a single token. If a request requires a scope the token does not have, the API returns 403 Forbidden.

Expiry#

All tokens have a mandatory expiry date set at creation. The maximum lifetime is one year. Expired tokens are rejected immediately at authentication time. Set the shortest expiry that fits your workflow and rotate tokens regularly.

Creating a token#

1. Go to User Settings → Personal Access Tokens
2. Enter a description (e.g., gitlab-ci-main-repo) and select the required scopes
3. Choose the token type:
   • Asymmetric: paste an ECDSA P-256 public key (generate one with devguard-cli key generate)
   • Symmetric: leave the public key field empty — DevGuard generates the Bearer token
4. Set an expiry date (required, max 1 year)
5. Click Create — the private key or Bearer token is displayed once
6. Copy it immediately and store it securely (e.g., as a CI/CD secret variable)

Using a token#

Pass the token to the DevGuard scanner via --token. The scanner detects the token type automatically and handles signing or Bearer auth accordingly:

Or via environment variable:

For direct API calls with asymmetric tokens, the request must be signed. The signed request includes:

• X-Fingerprint — identifies which public key to verify against
• Signature-Input — describes what was signed
• Signature — the ECDSA-P256 signature
• Content-Digest — SHA-256 digest of the request body

For direct API calls with Bearer tokens:

Token lifecycle#

Viewing tokens#

All active tokens are listed under User Settings → Personal Access Tokens. Each entry shows:

• Description
• Scopes
• Creation date
• Expiry date
• Last used timestamp — useful for spotting tokens that are no longer in use

Revoking a token#

From the UI: Find the token in the list and click the delete button. You must be logged in.

By private key (for asymmetric tokens — useful for scripted revocation):

This derives the fingerprint from the private key and deletes the matching token. No session authentication is required — possession of the private key is sufficient proof of ownership.

Related#

• Create and Manage API Tokens — step-by-step guide to creating tokens
• Authenticate with the API — making API requests with a token
• Scan with GitLab CI — passing a token to the scanner in a pipeline