Authentication and permissions

Credential types

Never put credentials in URLs or source control. Keep application keys on a trusted server or in CI secrets, not in browser JavaScript. The full API key appears only in its creation response.

Verify the current identity

curl --fail-with-body "$DAGY_API_URL/me" \
  -H "Authorization: Bearer $DAGY_TOKEN"

For a session, the response contains user_email, org_id, and role. An API key's role can be empty because permissions come from scopes. GET /users/me adds org_name and account metadata.

A session can select a workspace using X-Org-Id. Obtain IDs from GET /orgs. The workspace must be one of the user's memberships. If selection cannot be resolved, the API can fall back to another membership; verify /me with the same header before writes. An API key always uses its creation workspace.

Create, inspect, and revoke API keys

Creating or deleting a key requires admin.api_keys, held by owners and admins. For a service that deploys flows and runs them:

curl --fail-with-body -X POST "$DAGY_API_URL/api-keys" \
  -H "Authorization: Bearer $DAGY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "release-worker",
    "scopes": ["flows.read", "flows.write", "runs.read", "runs.trigger"],
    "expires_in_days": 30
  }'

Here DAGY_TOKEN must already contain a credential allowed to manage keys. For a working bootstrap from dagy login, use Create an application key.

The response includes key_id, key, key_prefix, name, scopes, created_at, and expires_at. Store key immediately in your secret manager. expires_at is Unix seconds; no expiry is null. Omitting scopes defaults to flows.read and runs.read. An empty scopes list grants full owner-equivalent access. Supply an explicit nonempty list for application keys.

Rotate by creating a replacement, updating the application, verifying it works, and deleting the old key. There is no in-place rotation or scope update endpoint. A user's logout does not revoke their API keys.

API key scope compatibility

Some endpoint families require an additional API key scope before the granular feature permission. Include both when designing a key:

The literal admin key scope satisfies these compatibility checks; it is not a wildcard and does not replace granular permissions. A key with only admin cannot create a key. An owner/admin session does not need these API-key-specific scopes.

A run submission and monitoring key usually needs only runs.trigger and runs.read. A release key also needs flows.read and flows.write. Add scheduling or environment permissions only when the service manages those resources.

Workspace roles

There are four workspace roles and 35 granular permissions. Role permissions apply where the operation requires them; identity and several convenience/account reads require authentication without an additional granular permission. Consult the endpoint index.

secrets.read includes decrypted values. Do not give the developer role to someone who should only see secret names. The current flow-delete operation requires flows.write; the separate flows.delete permission does not restrict it to owners/admins. Workspace administration is distinct from reserved platform administration; organization ownership does not grant cross-workspace access.

Read the role matrix with GET /orgs/{org_id}/roles. Manage membership using Workspace administration.

Access-token exchange

POST /auth/login is an authenticated exchange, not sign-in from an email address alone. Supply a valid bearer credential that proves the same email:

curl --fail-with-body -X POST "$DAGY_API_URL/auth/login" \
  -H "Authorization: Bearer $SIGN_IN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"developer@example.com"}'

The response contains access_token, token_type: "Bearer", and expires_at. An existing unexpired access token may be returned again. A missing email claim, explicitly unverified email, or email mismatch returns 403. There is no general refresh-token endpoint; repeat authenticated sign-in when needed.

POST /auth/logout with a valid session requests revocation of the user's active Dagy access sessions. dagy logout also removes the local credential file. It does not terminate an identity-provider session or revoke keys.

Device authorization for CLI integrations

Most users should run dagy login. To implement a device client:

1. POST /auth/device/start with {}. Keep device_code private. Show the eight-digit user_code and direct the user to the web application's /cli-callback page.
2. The signed-in browser sends POST /auth/device/approve with {"user_code":"12345678"} and its valid bearer token. Approval binds to that user and workspace.
3. The device polls POST /auth/device/token with {"device_code":"THE_RETURNED_DEVICE_CODE"} at the returned interval.
4. On success, save access_token, expires_at, user_email, and org_id securely.

The grant expires after five minutes and can be consumed once. Pending responses use HTTP 202 with status: "authorization_pending" and interval: 2. Concurrent redemption can return status: "slow_down" and interval: 3. Honor these intervals. HTTP 410 means start a new grant. Final 200 includes workspace_name; approval does not deliver the token to the browser.

Keep the device code and token out of URLs, telemetry, and logs. Complete models are in the OpenAPI reference.