Skip to content

Projects, roles and tokens

DV Forge organizes access in two levels: organizations, which hold people and their roles, and projects, which hold results. This page explains how people get in, what each role can do, how to create a project, and how to issue API tokens so CI can upload results. Creating projects and managing tokens are done through the API today. The requests are shown below.

Organizations and projects

An organization is your company's account. It contains projects, and everything else (regressions, signatures, labels, rules, saved searches, API tokens) belongs to exactly one project.

You refer to a project by its project ref, org-slug/project-slug, for example acme/soc-top. On any API request, pass it as ?project=:

curl -s "https://api.daruur.cloud/v1/signatures?project=acme/soc-top" \
  -H "Authorization: Bearer $DVF_TOKEN"
  • A bare project slug (?project=soc-top) works when only one of your organizations has a project with that slug. Otherwise the API answers 400 ambiguous project; use org-slug/project-slug.
  • Without ?project=, the API uses your landing project: default in your oldest organization, else that organization's first project alphabetically.
  • In the web app, the project switcher sets ?project= for you. See The project switcher.

To see your organizations, your role in each, and the projects you can open, call GET /v1/me:

curl -s https://api.daruur.cloud/v1/me -H "Authorization: Bearer $DVF_SESSION"
{
  "subject": "user_…",
  "user_id": "1d0c…",
  "orgs": [{ "id": "8b2e…", "slug": "acme", "name": "Acme", "role": "triager" }],
  "projects": [
    {
      "id": "c41f…", "org_id": "8b2e…", "org_slug": "acme",
      "slug": "soc-top", "name": "SoC top level",
      "ref": "acme/soc-top", "role": "triager"
    }
  ],
  "default_project": "acme/soc-top"
}

How people get in

  1. Invitation. Sign-in is by invitation. Your organization's admin arranges one for you.
  2. First sign-in. You sign in at https://app.daruur.cloud. The first time, DV Forge creates a personal organization for you, with one project named default, and makes you its org_admin. You can try DV Forge there on your own.
  3. Joining your team's organization. To work in your team's projects, you need to be a member of its organization with a role.

Membership is managed by DV Forge today

There's no screen or API yet for adding people to an organization, changing a role, or removing someone. Ask your DV Forge contact, and tell them the role each person needs.

When someone leaves an organization, they stop seeing its projects and its notifications. Signatures assigned to them keep showing them as the assignee until someone reassigns them.

Roles

Each person has one role per organization, and it applies to every project in that organization. There are no per-project roles: despite its name, project_admin is granted for the whole organization.

The roles form a ladder. Each role can do everything the roles below it can, plus:

Role Adds
viewer See everything in the organization's projects: regressions, jobs and logs, signatures and their history, the triage queue, rules and the rule run log, root-cause runs. Export CSV. Watch signatures.
member Upload results (dvforge upload or Ingest regression). Comment and attach files. Save searches. Start and delete root-cause runs. Delete regressions (through the API).
triager Change a signature's status (except waiving it) and confirm a root cause. Assign, label, link bugs, edit the title and classification. Merge, split and act on duplicate suggestions. Bulk actions. Create, edit and reorder rules, except rules that run the agent.
project_admin Waive signatures. Delete anyone's comments and attachments. Edit or delete shared saved searches. Write rules that run the agent. Change bucketing and re-bucket. Create projects. Issue and revoke API tokens. Point a project at a data plane.
org_admin Register and revoke data planes.

Permissions has the full matrix, action by action.

The app hides or disables what your role can't do. Hover over a grayed-out control to see the role it needs, where it says. The API is the authority either way: a request above your role gets 403 with a message such as requires triager role.

Create a project

Creating projects is API-only today. You need the project_admin or org_admin role in the organization, and you call the API as yourself (see Calling the API as yourself). An API token can't create projects.

curl -s -X POST https://api.daruur.cloud/v1/projects \
  -H "Authorization: Bearer $DVF_SESSION" \
  -H "Content-Type: application/json" \
  -d '{"org": "acme", "slug": "soc-top", "name": "SoC top level"}'
Field Rules
org The organization's slug. Optional, but pass it: without it the project goes to your oldest organization, which may be your personal one.
slug 1 to 64 characters: lowercase letters, digits and hyphens, starting with a letter or digit. Unique within the organization, and it can't be changed later.
name 1 to 255 characters. The name the project switcher shows.

The response is 201 with the new project, including its ref. Possible errors:

Status Meaning
403 requires project_admin role Your role in that organization is too low.
404 org not found You aren't a member of an organization with that slug.
409 project slug already exists Pick another slug.
422 The slug or name breaks the rules above.

The new project appears in everyone's project switcher in that organization after their next page load. There's no API to rename or delete a project yet.

API tokens

An API token lets a machine, usually a CI job, call DV Forge without a person's sign-in. Each token belongs to exactly one project and sees only that project. A token looks like dvf_3f9a1c2e_…: the 8 characters after dvf_ are its prefix, which token lists show so you can tell tokens apart without seeing the secret.

Scopes

Scope Acts as Use it for
read viewer Read-only integrations: dashboards, exports, reports.
ingest:write member dvforge upload from CI. It includes everything read allows.

Even where the role would allow it, a token can't do things that need a person: comment, attach files, watch signatures, save searches, read notifications, list the organization's members, create projects, manage tokens, or list or register data planes. Those requests get 403.

An ingest:write token can do more than upload

Because it acts as a member, an ingest:write token can also delete regressions and runs and start root-cause runs through the API. Give each pipeline its own token, set an expiry, and revoke tokens you no longer use.

Calling the API as yourself

Issuing, listing and revoking tokens are API-only today, and these calls must be made as a signed-in person with the project_admin or org_admin role: an API token can't mint tokens (403 api tokens cannot mint tokens). Pass your own session token as the bearer. The examples on this page use the placeholder $DVF_SESSION for it.

Note

The app doesn't display your session token. If you can't obtain one, ask your DV Forge contact to issue the CI token for you.

Create a token

curl -s -X POST "https://api.daruur.cloud/v1/tokens?project=acme/soc-top" \
  -H "Authorization: Bearer $DVF_SESSION" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-nightly", "scopes": ["ingest:write"], "expires_at": "2027-06-30T00:00:00Z"}'
Field Rules
name 1 to 255 characters. Name it after the pipeline that uses it.
scopes At least one of read and ingest:write.
expires_at Optional, ISO 8601. Omit it for a token that never expires. It can't be changed later.

The response is 201:

{
  "id": "5e7d…",
  "project_id": "c41f…",
  "name": "ci-nightly",
  "prefix": "3f9a1c2e",
  "scopes": ["ingest:write"],
  "created_at": "2026-11-17T15:04:05Z",
  "expires_at": "2027-06-30T00:00:00Z",
  "last_used_at": null,
  "revoked_at": null,
  "token": "dvf_3f9a1c2e_…"
}

The secret is shown once

token appears only in this response. DV Forge stores a hash, not the secret, so it can't show it again. Put it straight into your CI secret store (for example as DVFORGE_TOKEN). If you lose it, revoke the token and create a new one.

List tokens

curl -s "https://api.daruur.cloud/v1/tokens?project=acme/soc-top" \
  -H "Authorization: Bearer $DVF_SESSION"

The response lists the project's tokens, newest first, with the same fields as above but without token. Revoked tokens stay in the list with revoked_at set. last_used_at tells you whether a token is still in use.

Revoke a token

curl -s -X DELETE "https://api.daruur.cloud/v1/tokens/5e7d…" \
  -H "Authorization: Bearer $DVF_SESSION"

The response is 204, and revocation is immediate. Revoking a token twice is harmless.

Expiry and rotation

A revoked or expired token gets 401 invalid api token; the CLI exits with code 3. Tokens can't be edited, so to rotate one: create the new token, update your CI secret, check that the new token's last_used_at is set, then revoke the old one.

Access errors

You get Because
401 No bearer token, or the token is invalid, revoked or expired.
403 You can see the project, but your role or token scope is too low, or a token tried something only a person can do. The message names what's missing.
404 The item doesn't exist, or it's in a project you can't see.

DV Forge answers 404, never 403, for anything in a project you can't see, including signatures, regressions, runs, comments and tokens fetched by id. That way ids never reveal what exists in another organization. A token that names a project other than its own gets 404 project not found.