API Tokens

Overview

An API token lets a script or tool authenticate against the devguard API without a browser session. Every token starts with the prefix dvg_ and is sent as a Bearer token in the Authorization header.

A token is bound to your account. A request made with it can do everything you can do, in every organization you belong to. There are no scoped, read-only or single-organization tokens yet, so the account you create the token from is the blast radius.

Treat a token as a high-value secret

Store it as a masked secret in your CI system, never commit it to a repository, and delete it as soon as it is exposed or no longer needed. Anyone holding the token is you, everywhere you have access.

Creating a token

Only an owner or an admin can create a token. Members do not see the button.

• Name: A label so you can recognize the token later, for example "CI evidence push". The name is visible in the list.
• Expiry: 7, 30, 90 or 360 days, or never. The form defaults to 90 days. For anything unattended, either choose never or put the rotation date in a calendar, because an expired token stops the job with no warning and no notification.
• The secret is shown once, at creation. Copy it then. If you lose it, delete the token and create another; there is no way to reveal it again.

What a token can do

A token authenticates as you, and then the normal permission rules apply per organization:

• Owner and admin can read and write everything their role allows.
• Member can read, but write calls are refused with 403. A member's token authenticates successfully and is then rejected at the point of writing, so a failure often looks like a network problem when it is really a role problem.

The token reaches the REST API under /api/, which is the same surface documented in the API reference. It does not reach the internal endpoints the web app itself uses.

Paths end in a slash

The REST API is trailing-slash sensitive: /api/whoami/ works, /api/whoami does not. Calls are also meant to come from a server or a terminal rather than a browser, because browser origins are not permitted.

Revoking

Deleting a token revokes it immediately. Anything still using it fails on its next request. There is no grace period and no soft delete, so rotate by creating the replacement first, updating whatever uses it, then deleting the old one.

Every call a token makes is attributed to you in the audit log, so a shared token makes the log less useful. Prefer one token per purpose.

Calling the API

Send the token in the Authorization header as a Bearer token, and pass the organizationId in the request body. Some common calls:

curl -X GET "https://app.devguard.ch/api/assets/?organizationId=UUID" \
  -H "Authorization: Bearer dvg_your_token_here" \
  -H "Content-Type: application/json"

The API reference lists every available endpoint and resource.

Rate limits

Each token is limited to 1000 requests per hour. The limit is per token, not per account, so splitting jobs across separate tokens also splits their budgets.

Responses

The devguard CLI

The CLI is the main consumer of these tokens. It runs commands you declare on a schedule and pushes their output into an evidence record, so the proof stays current instead of being uploaded once a year.

Create the token here, then follow the setup in CLI. That page also has a connection check that confirms the token works before you wire anything into a pipeline.