API Keys

API keys let scripts, CI jobs, other Dagu servers, and external tools call the Dagu API without an interactive login.

When To Use API Keys

Use an API key when you need:

• CI/CD to start or enqueue workflows
• automation to read run status or outputs
• one Dagu server to talk to another through remote nodes
• a long-lived machine credential with a clear role and audit trail

API keys require Builtin Authentication.

Creation Limits

If the server has an API key creation limit, the limit applies only to new key creation. Existing keys are not deleted or disabled by the limit. When the limit has already been reached, Dagu shows a warning on the API key management page and blocks new key creation until enough keys are deleted or the limit changes.

What You Manage

Each API key has:

• a name
• an optional description
• a role
• optional workspace limits
• accepted surfaces, such as REST API and MCP
• an attribution class, either user-owned or service account
• last used tracking in the UI

The full secret is shown only once when you create the key.

Create An API Key In The Web UI

1. Sign in as an admin
2. Open Admin > API Keys
3. Click Create API Key
4. Enter a name and optional description
5. Choose the role
6. Choose All workspaces or Selected workspaces
7. Choose the accepted surfaces
8. Choose user-owned or service-account attribution
9. Create the key and store the secret immediately
10. For a key that accepts the mcp surface, click Copy MCP setup prompt

Use An API Key

Send it as a Bearer token:

curl -H "Authorization: Bearer $DAGU_API_KEY" \
  http://localhost:8080/api/v1/dags

For CLI usage:

export DAGU_API_TOKEN=$DAGU_API_KEY
dagu status

Accepted Surfaces

API keys can be scoped to the public interfaces that should accept them.

Surface	Use
rest_api	REST API, CLI remote contexts, and related HTTP API usage.
mcp	The built-in MCP server.

Use an MCP-only key for an AI tool that should operate through MCP but should not call the REST API directly. Use both surfaces when the same automation identity needs both REST and MCP.

Legacy API keys created before surface metadata existed are treated as both rest_api and mcp for compatibility.

Connect An MCP Client

The dialog that reveals a new secret also offers Copy MCP setup prompt when the key accepts the mcp surface. The button copies instructions for an AI coding agent that already carry this server's MCP endpoint and the new key, so the agent can write the connection settings in whatever format its own client expects.

The endpoint in the prompt is built from the address you are using in the browser, because Dagu does not publish its configured public URL to the web UI. If your MCP client reaches Dagu at a different address, edit the URL after pasting. The button is hidden while a remote node is selected, since a key created there belongs to that node's server rather than this one.

The button appears only on that dialog, because Dagu never stores the plaintext secret. To set up a client later, follow MCP Clients and supply the key yourself.

Attribution

API keys can be attributed as either:

Attribution	Use
service_account	Shared automation identity, such as a CI runner or team MCP client.
user_owned	A key owned by a specific Dagu user when audit logs should attribute actions to that user.

For MCP usage, prefer individual user-owned keys when you need per-user auditability. Prefer service-account keys for shared bots, CI jobs, and integrations with a stable machine identity.

Roles And Workspace Access

API keys use the same role model as users.

Role	Typical Use
admin	Full control, including admin endpoints
manager	Workflow administration plus audit/event visibility
developer	Create, edit, run, and troubleshoot workflows
operator	Run and stop workflows
viewer	Read-only automation

Workspace access works the same way as it does for users:

• All workspaces: the key's role applies everywhere
• Selected workspaces: use a top-level viewer role and grant per-workspace roles

Example for a key that can deploy only inside ops:

{
  "role": "viewer",
  "workspaceAccess": {
    "all": false,
    "grants": [
      { "workspace": "ops", "role": "developer" }
    ]
  }
}

See User Management for the workspace model.

Create Keys By API

TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}' | jq -r '.token')

curl -X POST http://localhost:8080/api/v1/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-pipeline",
    "description": "Workflow automation",
    "role": "operator",
    "workspaceAccess": { "all": true },
    "allowedSurfaces": ["rest_api"],
    "attributionClass": "service_account",
    "serviceAccountName": "ci-pipeline"
  }'

The response includes the key secret once. Save it before you leave the page or discard the response output.

When the server's API key creation limit has been reached, POST /api/v1/api-keys returns 403 Forbidden.

CI/CD Example

name: Trigger Workflow
on:
  push:
    branches: [main]

jobs:
  run-dagu:
    runs-on: ubuntu-latest
    steps:
      - name: Start deploy workflow
        env:
          DAGU_API_KEY: ${{ secrets.DAGU_API_KEY }}
        run: |
          curl -X POST "https://dagu.example.com/api/v1/dags/deploy/start" \
            -H "Authorization: Bearer $DAGU_API_KEY" \
            -H "Content-Type: application/json" \
            -d '{"params":"{\"version\":\"'${GITHUB_SHA}'\"}"}'

Remote Node Example

API keys are also a good fit for cross-server access:

remote_nodes:
  - name: production
    api_base_url: https://prod.example.com/api/v1
    auth_type: token
    auth_token: ${PROD_DAGU_API_KEY}

Manage Existing Keys

Admins can list, inspect, update, and delete API keys from the UI or API.

Action	Endpoint
List keys	GET /api/v1/api-keys
Get one key	GET /api/v1/api-keys/{keyId}
Create key	POST /api/v1/api-keys
Update key	PATCH /api/v1/api-keys/{keyId}
Delete key	DELETE /api/v1/api-keys/{keyId}

Good Practices

1. Use a separate key per service or pipeline.
2. Give each key the smallest role it needs.
3. Scope keys to workspaces when possible.
4. Limit each key to the surfaces it actually needs.
5. Use user-owned keys for MCP clients when individual audit attribution matters.
6. Keep any server-side key creation limit in mind when planning per-service key separation.
7. Rotate keys regularly.
8. Delete keys you no longer use.
9. Store keys in your normal secret manager rather than in source control.

Related Pages

• Builtin Authentication
• User Management
• Remote Nodes Authentication
• MCP Authentication