Organization tokens

Overview

An organization token is an API token that belongs to the organization rather than to a person. Use one for anything the organization depends on: a CI pipeline that pushes evidence, an export into your SIEM, an internal script. Every organization token starts with the prefix dvgo_ and is sent the same way as a personal token, as a Bearer token in the Authorization header.

Only owners and admins see this page, and only they can create or revoke organization tokens.

Compared with a personal token from Account → Tokens:

• It survives its creator. The token keeps working when the person who created it leaves the organization, is deactivated or deletes their account. Once that account is gone, the list names the creator as Former member.
• It reaches one organization. The token acts in this organization and in no other.
• It carries only the access you choose. You decide what it may read and write when you create it, and that choice is fixed. To change it, create a new token and revoke the old one.

Creating a token

• Token name: up to 32 characters. The audit log shows this name for everything the token does, so name it after its job, for example "CI evidence push".
• Expiration: 30, 90 or 365 days, or never. The form defaults to 90 days. An expired token stops working with no warning, so for an unattended job either choose never or put the rotation date in a calendar.
• Access: what the token may read and write, described below. At least one choice is required.

The secret is shown once, at creation. Copy it then and store it as a masked secret in your CI system. If you lose it, revoke the token and create another; there is no way to reveal it again.

Access: reads, writes and areas

Access is chosen per area. An area groups the parts of devguard that belong together: Risks covers risks, risk reviews, treatment actions, threat classes and vulnerability classes, and Evidence covers evidence, its categories and its files.

• Read, All areas: the token reads the whole organization, and this is the only choice that also covers areas added later. The MCP server needs it and accepts an organization token only when it reads everything.
• Read, per area: without All areas, reads are limited to the areas you switch on, and a request outside them is refused with 403. Tokens like this are meant for the REST API.
• Write: chosen per area, independently of what the token reads.
• Write, All areas: switches on every writable area at once.

A view returns what it embeds

Reading an area means the token may run the requests that area guards, and each request returns everything its view shows, including what it embeds from other areas. A token that reads only Controls & frameworks still sees the names of the evidence linked to a control, because the control view shows them.

Some areas can only ever be read: Audit log, Search, Billing and Directory (the organization, its people and its tokens). An organization token therefore never creates other tokens, manages members, changes the organization's settings or touches its plan.

Expiry and revocation

• An expired token stops working on its next request and stays in the list as Expired until you revoke it. Its creator is no longer shown, because the key that recorded it is gone.
• Revoke ends a token immediately. Anything still using it fails on its next request. There is no grace period, so rotate by creating the replacement first, switching whatever uses the token, and then revoking the old one.
• A revoked token leaves the list. What it did stays in the audit log.

Audit log

Everything an organization token does appears in the audit log under the token's name, the same way a person's actions appear under theirs. Creating and revoking a token is logged too, under the admin who did it. One token per purpose keeps the log readable.

Calling the API

Requests, rate limits and response codes work as described under Tokens. An organization token acts in its own organization only, so a request naming another organization is refused.