Tokens

Overview

An API token lets a script or tool authenticate against the devguard API without a browser session. Every personal token starts with dvg_ (organization tokens start with dvgo_) and is sent as a Bearer token in the Authorization header.

A personal token acts as you, in one of two modes:

• All organizations: a request made with it can do everything you can do, in every organization you belong to. The account you create the token from is the blast radius.
• One organization: the token is bound to a single organization and carries only the access you choose (what it may read, and which areas it may write), never more than your own role allows there.

A personal token stops working when you leave the organization it reaches. For anything an organization depends on, such as a pipeline that has to keep running when people come and go, use an organization token instead. A connected app is granted exactly one organization and only the permissions it asked for.

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 the token reaches.

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.
• Access: All organizations (full access to everything you can do) or One organization. For one organization, pick the organization (you start on your active one) and what the token may read and write. At least one choice is required, and organizations where you are an employee, an external contact or deactivated are not offered.
• 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.

A token bound to one organization is also held to the access chosen for it: a request for another organization, or for anything it may not read or write, is refused with 403.

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 3000 verifications per hour. A single REST call spends three of them (it resolves the token, then your session and your memberships), so a token is good for roughly 1000 REST calls 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 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.

On a machine with a browser it needs no token: devguard login opens one, you pick the organization that machine may act in, and the login then appears under Connected apps, where an organization admin can revoke it. In CI, where nothing can open a browser, create a token here and pass it as DEVGUARD_API_KEY instead.

The setup in CLI covers both paths. That page also has a connection check that confirms the token works before you wire anything into a pipeline.