Connect to Dagy

Sign in and choose a workspace

1. Open dagy.io and complete sign-in. If your organization uses another application URL, open that instead.

   Sign in with an email address and password, or with Google. Creating an account with an email address sends a six-digit confirmation code to that address; the code is valid for ten minutes, and you can request another from the same screen. If you forget your password, choose Forgot password? on the sign-in page to receive a reset code; you do not need an administrator to reset it for you.

2. Select the workspace you intend to use. First sign-in provisions a personal workspace when the account has no membership. For an existing team, ask its owner or admin to add your sign-in email.

3. Set the complete API URL and sign in from your terminal:

export DAGY_API_URL="https://api.dagy.io/app"
export DAGY_APP_URL="https://dagy.io"
dagy login

The CLI displays an eight-digit code and opens the browser approval page. Enter the code in the signed-in browser and approve it within five minutes. The CLI saves the resulting access token under ~/.dagy/credentials, or the directory selected by DAGY_LOCAL_DIR. Treat this file as a secret.

The API and application URLs must refer to the same deployment. DAGY_API_URL is needed for subsequent remote CLI commands even when login used its hosted default. See CLI configuration to persist a profile.

Verify your connection

The Python client can use saved CLI credentials without putting a token in source:

import os
from dagy.client import DagyClient

client = DagyClient(os.environ["DAGY_API_URL"])
print(client.list_flows())

A new workspace can correctly return an empty items list. To inspect the identity and create a service key, use this standard-library client in a local Python file:

import json
import os
from pathlib import Path
from urllib.request import Request, urlopen

base = os.environ["DAGY_API_URL"].rstrip("/")
credential_dir = Path(os.environ.get("DAGY_LOCAL_DIR", "~/.dagy")).expanduser()
credentials = json.loads((credential_dir / "credentials").read_text())

def api(method, path, payload=None):
    headers = {"Authorization": f"Bearer {credentials['access_token']}"}
    if credentials.get("org_id"):
        headers["X-Org-Id"] = credentials["org_id"]
    body = None
    if payload is not None:
        headers["Content-Type"] = "application/json"
        body = json.dumps(payload).encode()
    request = Request(base + path, data=body, headers=headers, method=method)
    with urlopen(request, timeout=30) as response:
        return json.load(response)

identity = api("GET", "/me")
print(identity)  # Confirm org_id, user_email, and role before creating a key.

If the workspace is wrong, select the correct one in the browser and repeat dagy login, or use workspace selection in your application. The credential file is shared by CLI profiles; changing a profile alone does not change the signed-in account.

Create an application key

An owner or admin can extend the script above to create a key that deploys and triggers workflows. Use a session with that role; an ordinary developer cannot create keys.

# Check the target path before creating a key; use a new filename if it exists.
key_path = Path("dagy-service-key.json")
if key_path.exists():
    raise RuntimeError("Choose a new key filename before continuing")

key = api("POST", "/api-keys", {
    "name": "release-worker",
    "scopes": ["flows.read", "flows.write", "runs.read", "runs.trigger"],
    "expires_in_days": 30,
})

# Create a file readable only by the current user; refuse to overwrite a file.
fd = os.open(key_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
with os.fdopen(fd, "w") as output:
    json.dump(key, output, indent=2)
print("Created", key["key_id"], "and saved it to", key_path)

Transfer the key value to your application or CI secret manager, then remove the temporary file according to your organization's process. Never commit it. The API cannot return the full key again. If saving the response fails, list keys, revoke the newly created key by its name/ID, and create a replacement.

Settings → API keys → New Key currently creates default flows.read and runs.read scopes. That key can inspect flows and runs. Use the API example above when the integration needs to write or trigger. The scope reference lists permissions for scheduling and administration.

Use the key in your application

Have your secret manager supply DAGY_SERVICE_KEY to this example:

import os
from dagy.client import DagyClient

client = DagyClient(
    os.environ["DAGY_API_URL"],
    token=os.environ["DAGY_SERVICE_KEY"],
)
print(client.list_flows())

The explicit token argument is required for this pattern. The client does not automatically discover a key from DAGY_SERVICE_KEY or DAGY_TOKEN.

Resolve common connection problems

Continue with your first local flow, then deploy it. Read Errors and retries before adding automated retries.