Authentication

Dalea offers three authentication paths for programmatic access. Each is optimised for a different scenario:

Pick whichever matches the actor. If a person is in front of the screen, use OAuth or MCP. If a script runs without anyone watching, use an API key.

OAuth 2.1 — apps acting as a user

Use when your application authenticates end users and acts on their behalf. Standard OAuth 2.1 flow:

┌──── Your app ────┐                ┌──── Dalea ────┐
│                  │  /authorize    │               │
│   Browser ──────────────────────► │  consent page │
│                  │                │               │
│                  │  ?code=...     │               │
│   Browser ◄─────────────────────  │               │
│                  │                │               │
│   Server  ──────────────────────► │  /token       │
│                  │  exchange code │               │
│                  │  ◄──────────── │  access+refresh
└──────────────────┘                └───────────────┘

Standard scopes:

• openid profile email — identity
• offline_access — get a refresh token
• mcp:read — call read-only MCP tools (only relevant if your app is also an MCP client)
• mcp:write — call destructive MCP tools (rarely granted to apps; usually in-app chat only)

Set up an OAuth client in Settings → Workspaces → OAuth clients. You'll get a client_id and client_secret; the secret stays on your server only.

Workspace API keys — for scripts

When a script runs without a user, an API key is the right choice.

Creating one

1. Settings → Security → API keys → New key

   Pick the workspace the key should access (one workspace per key).

2. Pick a role

   Same five workspace roles as for human users — Owner, Data Engineer, Editor, Commenter, Viewer. Pick the most restrictive role that gets your job done. A nightly read-only export only needs Viewer.

3. Optional: scope to specific permissions

   Beyond role, you can pin the key to a subset of actions (read documents, write to environment X). Useful for least-privilege scripts.

4. Set an expiry

   30 days, 90 days, 1 year, or never. Default is 90 days; rotate proactively.

5. Copy the key once

   Dalea displays the key string exactly once. Store it in your secret manager immediately — there's no way to retrieve it later.

Using a key

Send it as a Bearer token on the standard Authorization header:

curl https://dalea.app/api/v1/workspaces/$WORKSPACE/documents \
  -H "Authorization: Bearer $DALEA_API_KEY"

import requests

resp = requests.get(
    f"https://dalea.app/api/v1/workspaces/{ws}/documents",
    headers={"Authorization": f"Bearer {api_key}"},
)
resp.raise_for_status()
for doc in resp.json()["items"]:
    print(doc["title"])

const resp = await fetch(
  `https://dalea.app/api/v1/workspaces/${ws}/documents`,
  { headers: { Authorization: `Bearer ${apiKey}` } },
);
const { items } = await resp.json();

Revoking

Same Settings page. Revocation is immediate. If a key is compromised, revoke it first, then issue a new one — never the other way round.

MCP tokens — for LLM tool clients

If you're building an MCP-aware client (a Claude Desktop alternative, a custom agent), use the MCP OAuth flow. It's structurally OAuth 2.1 but tokens are short-lived and auto-refresh; access is bound to one workspace and one role.

See MCP for tool builders for the full flow and example client.

Choosing per scenario

A nightly script that pulls a CSV of new results

Workspace API key, Viewer role, scoped to one environment.

An internal web app where each scientist views their own data

OAuth — each user signs in with their own Dalea account.

A Slack bot that posts when a result batch closes

Workspace API key, Editor role; scoped to read result batches and read documents.

A custom Claude Desktop alternative

MCP OAuth flow.

A Cursor instance you want to use as a co-analyst

MCP OAuth flow — same as Claude Desktop.

A Python notebook running on a researcher's laptop

Workspace API key, scoped to that researcher's workspace and role.

Security notes

• Never commit secrets. Use environment variables and a secret manager.
• Scope down. Owner is rarely the right key role. Most scripts are fine with Viewer or Editor.
• Rotate. Set keys to 90-day expiry. Have a rotation job in your secret manager rather than rotating by hand.
• Audit. Every API call is logged with the key's identity, the actor it represents, and the action. See Audit logging.

What's next