API Keys — User Guide

Audience: Anyone automating Dagen from scripts, CI/CD, iPaaS (Zapier, n8n), or custom backends.

Overview

API Keys (/api-keys) are how non-browser clients authenticate to External API v1 and A2A (POST /a2a). Keys are workspace-scoped: they only see agents, workflows, and jobs for the workspace active when the key was created (workspace id is tied to the key).

The consolidated API Management view (/api-management) repeats API Keys plus tabs for REST v1 and A2A Protocol with live curl and JSON-RPC examples tied to your current origin.

What API keys unlock

Capability Typical use
Agent chat (sync JSON) POST /api/v1/agent/chat — full reply in one response
Workflow run + poll POST /api/v1/workflow/:id/run + GET .../runs/:run_id
List agents / workflows Discovery for dynamic integrations
A2A JSON-RPC Interop with agent ecosystems (message/send, tasks/get, tasks/cancel)

Details: External API.

Page layout

Header

  • Title API Keys, subtitle explaining integration purpose.
  • Create API Key opens the creation dialog.

Quick Start (expandable)

Step-by-step: create key → copy once → use X-API-Key. Includes three curl examples (list agents, agent chat, run workflow) with window.location.origin as base URL.

Keys table

Column Meaning
Name Your label (e.g. “Prod nightly ETL caller”)
Key Prefix only (dg_xxxx…); full secret never stored for display
Scopes Agents (blue) and/or Workflows (purple) chips
Status Active / Inactive; Expired if past expiry date
Rate limit e.g. 60/min
Requests Lifetime call count
Last used Relative (“5m ago”) or Never
Created Human-readable date
Actions Activate/Deactivate, Regenerate, Delete

Empty: CTA to create first key. Loading: Spinner centered.

Create API Key dialog

Field Rules
Name Required
Scopes Toggle Agents and/or Workflows; at least one required
Rate limit Integer 1–600 req/min; default 60
Expiration Optional date picker; must be after today if set

Create is disabled until name + scope are valid. Dialog is persistent so you don’t lose data by accidental click-outside.

After create or regenerate

A second dialog appears:

  • Warning: copy now — you cannot see the full key again.
  • Monospace full key + copy button (icon flips to checkmark ~2s on success).
  • Done closes the dialog.

Regenerate and delete

Action Behaviour
Regenerate Confirms that the old secret stops working immediately; new secret shown in the same “copy once” dialog
Delete Confirms loss of access for all consumers using that key
Deactivate Key returns 403 until reactivated

Snackbar confirms success/failure for operations.

Backend operations (for operators)

Action Effect
List GET /api/keys?workspace_id=…
Create POST /api/keys → returns one-time key field
Update PUT /api/keys/:id — e.g. toggle is_active
Delete DELETE /api/keys/:id
Regenerate POST /api/keys/:id/regenerate

Security practices

  • Rotate keys on engineer offboarding or suspected leak.
  • Scope minimally — workflows-only keys cannot hit agent chat.
  • Rate limits protect against runaway scripts.
  • Store keys in secret managers, not repositories.

Related

Last updated: February 21, 2026