Skip to content

API tokens

Scripts and MCP clients call the public API with an API token. A personal token acts as you. A team token acts under its own name. Either one can only use the scopes you picked.

You create, change and revoke tokens while signed in. A token can’t create or change a token, its own included.

  1. Open the gear menu and choose API tokens.
  2. Say what the token is for, pick when it Expires (30 days, 90 days, 1 year or no expiry) and tick the scopes it needs.
  3. Click Create token and copy the token.

You only see it once. If you lose it, revoke it and make another.

The same panel lists your tokens, your remaining rate-limit budget and each token’s calls by endpoint.

Send POST /api/tokens with your session cookie:

Terminal window
curl -X POST https://api.dagweave.com/api/tokens \
-H "Content-Type: application/json" \
-H "X-Requested-With: dagweave" \
-b "__Host-dagweave_session=$DAGWEAVE_SESSION" \
-d '{"name":"run dashboard","scopes":["runs:read"],"expiresInDays":90}'
Field Required Notes
name No A label so you can tell your tokens apart.
scopes Yes One or more scope names. Lowercased and de-duplicated. An unknown scope or an empty list is a 400.
expiresInDays No 1 to 730. Leave it out and the token never expires.

These cookie-authenticated calls need an X-Requested-With header with any value, or you get 403. Bearer calls under /api/v1 don’t.

Only give write scopes to tokens that need them. runs:write starts real runs, workflows:write overwrites workflows and workflows:delete removes them.

Success is 201:

{
"id": "...",
"name": "run dashboard",
"teamId": "...",
"scopes": ["runs:read"],
"createdAt": "2026-07-25T09:00:00Z",
"expiresAt": "2026-10-23T09:00:00Z",
"token": "dwk_..."
}

Put token in your secret store now. Dagweave keeps only its hash and can’t show it again.

Tokens start with dwk_, so secret scanners can spot a leaked one.

GET /api/tokens returns your tokens, newest first, revoked ones included. Each has id, name, teamId, scopes and createdAt, plus expiresAt, lastUsedAt and revokedAt once set. The token and its hash are never returned. lastUsedAt updates at most once an hour.

DELETE /api/tokens/{id} revokes a token and returns 204. The next call with it fails. You can only revoke your own tokens. Any other id gets 404.

Creating, changing and revoking tokens show up in your team’s audit log. The token itself is never logged. Every successful call made with a token is in the audit log too, reads as well as writes. Each entry names the token and the person who owns it. Reads are kept for 90 days.

You can add or remove scopes on a token you already have. It keeps its value, so nothing that holds it needs a new secret.

  1. Open API tokens and click Edit scopes on the token’s row.
  2. Tick or untick scopes and click Save scopes.

The token’s next call gets the new scopes. An MCP client reads its tool list when it connects, so reconnect it to see the tools the new scopes allow.

From a script, send PATCH /api/tokens/{id} with your session cookie and a scopes list. The same rules as creating apply: an unknown scope or an empty list is a 400. The reply is 200 with the token as GET /api/tokens shows it. A revoked or expired token, or one that isn’t yours, gets 404.

Terminal window
curl -X PATCH https://api.dagweave.com/api/tokens/$TOKEN_ID \
-H "Content-Type: application/json" \
-H "X-Requested-With: dagweave" \
-b "__Host-dagweave_session=$DAGWEAVE_SESSION" \
-d '{"scopes":["runs:read","git:read","git:write"]}'

GET /api/tokens/usage shows what’s left of your rate limit this window. It doesn’t count as a request.

{
"windowSeconds": 60,
"user": {"limit": 300, "remaining": 288, "reset": "2026-07-25T09:01:00Z"},
"team": {"limit": 1200, "remaining": 1102, "reset": "2026-07-25T09:01:00Z"}
}

Use a team token for anything that should outlive one person’s membership. A personal token stops working when its owner leaves the team, and its runs read as theirs. A team token keeps working, and runs and the audit log show its name, such as ci-provisioner (team token). The audit log still records who made it.

Owners and Admins manage them on the Team tab of API tokens. A team token needs a name and acts as an Admin of its team, narrowed by its scopes. Team tokens need the Business plan.

From a script, send the same fields to POST /api/tokens/team. GET /api/tokens/team lists them with createdByEmail, PATCH /api/tokens/team/{id} changes one’s scopes and DELETE /api/tokens/team/{id} revokes one.

A GitHub Actions job can swap its OIDC ID token for a Dagweave token that lasts 15 minutes. Nothing is stored in GitHub.

  1. On the Team tab, under GitHub Actions, trust the repository. Add a ref such as refs/heads/main or refs/tags/*, or an environment, so a pull request can’t get a token. Tick the scopes the job needs.
  2. Below the rules is the step to paste into your workflow, with your team ID already filled in. Click Copy and add it to the job. The job also needs id-token: write. A full job looks like this:
permissions:
id-token: write
contents: read
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
steps:
- name: Get a Dagweave token
run: |
ID_TOKEN=$(curl -sSf -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://app.dagweave.com" | jq -r .value)
DAGWEAVE_TOKEN=$(curl -sSf -X POST https://api.dagweave.com/api/v1/oidc/github/token \
-H "Content-Type: application/json" \
-d "{\"idToken\":\"$ID_TOKEN\",\"teamId\":\"YOUR_TEAM_ID\"}" | jq -r .token)
echo "::add-mask::$DAGWEAVE_TOKEN"
echo "DAGWEAVE_TOKEN=$DAGWEAVE_TOKEN" >> "$GITHUB_ENV"
- name: Start the run
run: |
curl -sSf -X POST https://api.dagweave.com/api/v1/workflows/wf-123/run \
-H "Authorization: Bearer $DAGWEAVE_TOKEN" \
-H "Idempotency-Key: $GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT" \
-H "Content-Type: application/json" \
-d '{"connectorId":"conn-1","namespace":"argo"}'

Dagweave checks the repository, ref and environment separately, so a cleverly named branch can’t match a rule it shouldn’t. The token is named github: org/repo@ref (workflow run N) in runs and the audit log.

To change what a trusted repository’s jobs may do, click Edit scopes on its rule. Jobs get the new scopes from their next exchange, and a token a job already holds keeps its scopes until it runs out. From a script, send PATCH /api/tokens/github-trust/{id} with your session cookie and a scopes list, the same way you change a token’s scopes.

Status Meaning
401 The ID token didn’t verify. Check the audience, and send the token straight away.
402 The team’s plan doesn’t include team tokens.
403 No rule on that team matches this repository, ref and environment.
429 Too many exchanges.

A personal token always acts in the team it was created in. If its owner leaves that team, every call gets 403. An expired or revoked token gets 401.

To rotate, create the new token, switch your script to it, then revoke the old one. Both work in the meantime.