# Authentication

> Learn how to authenticate with the Dailybot API using API keys or CLI Bearer tokens — including plan requirements, key lifecycle, member access, and the auth method matrix.

Language: en
Canonical: https://www.dailybot.com/developers/authentication
Markdown: send header `Accept: text/markdown` on any URL to receive Markdown instead of HTML.
Last Updated: 2026-07-09

---

# Authentication

All Dailybot API requests require authentication via an API key or CLI Bearer token. This page covers required headers, authentication methods, plan requirements, key lifecycle semantics, and which auth method works on which endpoint.

## API key authentication

Dailybot uses header-based authentication. Include your API key in the `X-API-KEY` header with every request.

### Required headers

| Header | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `X-API-KEY` | string | Yes | — | Your unique API key obtained from the Dailybot dashboard. |
| `Content-Type` | string | Yes | `application/json` | Must be set to application/json. |
| `Accept` | string | Yes | `application/json` | Must be set to application/json. |

```bash
curl -X GET "https://api.dailybot.com/v1/me/" \
  -H "X-API-KEY: $DAILYBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
```

**Response (200 OK):**

```json
{
  "id": "usr_abc123",
  "email": "you@company.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "role": "admin"
}
```

> **API keys work on ALL `/v1/` endpoints.** There is no server-side restriction limiting API keys to agent operations. See the [auth method matrix](#parity-matrix) for the full breakdown.

## Plan requirements

API keys require a paid Dailybot plan. Every request made with an API key is checked against the key owner's organization plan. The check runs on **every request** — not just at key creation.

| Condition | HTTP | `code` |
|-----------|------|--------|
| Key's owner is deactivated | 403 | `api_key_owner_inactive` |
| Organization is on a free plan | 403 | `plan_free_api_keys_forbidden` |
| Organization's plan lacks API access | 403 | `plan_missing_core_api_integrations` |

> **Cache behavior:** Plan eligibility is cached per-org for up to 60 seconds. After a plan upgrade, it may take up to 60 seconds for an existing key to start working again. No action needed on your side — just be aware when testing immediately after a plan change.

## owner vs. created_by

Every API key records two distinct users:

- **`owner`** — the user whose identity and role scope the key acts as. Every request made with this key sees the owner's data, scoped by the owner's role.
- **`created_by`** — the admin who minted the key. Nullable on historical keys. Used for auditing.

Organization admins can create a key that is owned by a member. That key inherits the member's scope, not the admin's — useful for integrations that need to operate with member-level permissions rather than admin-level.

## API key secret lifecycle (show-once)

API key secrets follow **show-once semantics** — the full plaintext key is only returned at the moment of creation or regeneration. After that, only the last 4 characters (`key_suffix`) are ever shown.

| Action | Full key visible? | What subsequent reads show |
|--------|:-----------------:|----------------------------|
| Create (`POST`) | ✅ Yes, in 201 response | `key_suffix` only (last 4 chars) |
| Regenerate (`PATCH` with `regenerate: true`) | ✅ Yes, in 200 response | `key_suffix` only |
| List / Detail (`GET`) | ❌ Never | `key_suffix` only |
| Update without regenerate (`PATCH`) | ❌ Never | `key_suffix` only |

### Response fields

| Field | On GET | On POST / Regenerate | Description |
|-------|:------:|:--------------------:|-------------|
| `key` | ❌ | ✅ | Full plaintext key — the only opportunity to copy it |
| `key_suffix` | ✅ | ✅ | Last 4 characters, e.g. `e1f2` |

**Masked display format:** `••••••••e1f2` (8 dots + 4-char suffix).

> **Copy the key immediately** after creation or regeneration — it cannot be retrieved again. Store it in a secrets manager or environment variable. If lost, you must regenerate the key.

### Create key example

```bash
curl -X POST "https://api.dailybot.com/api/org/api-keys/" \
  -H "Authorization: JWT $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Key"}'
```

```json
{
  "id": "uuid",
  "name": "Production Key",
  "key": "db_live_a1b2c3d4...e1f2",
  "key_suffix": "e1f2",
  "active": true,
  "owner": { "uuid": "...", "full_name": "..." },
  "created_by": { "uuid": "...", "full_name": "..." },
  "is_agent_key": false,
  "last_usage_at": null,
  "expiration": null,
  "created_at": "2026-07-09T..."
}
```

### List keys (key is hidden)

```json
{
  "count": 2,
  "results": [
    {
      "id": "uuid",
      "name": "Production Key",
      "key_suffix": "e1f2",
      "active": true
    }
  ]
}
```

## Member API key access

Non-admin organization members can now create, regenerate, and delete their own API keys. Previously, only admins had this access.

| Role | Can list | Can create | Can regenerate / delete | Scope |
|------|:--------:|:----------:|:-----------------------:|-------|
| **Admin** | All org keys | Regular + Agent keys; `for_user_id` allowed | Any key in the org | Full org |
| **Member** | Own keys only | Regular self-owned keys only | Own keys only | Self-scoped |

### Member restrictions

| Attempted action | Result |
|-----------------|--------|
| Create an agent key (`is_agent_key: true`) | `400` + `code: "agent_key_admin_only"` |
| Create a key for another user (`for_user_id`) | `403` + `code: "org_admin_required"` |
| Modify or delete another user's key | `404` (key is not in the member's queryset — no existence leak) |

## CLI Bearer tokens — free-plan allowlist

CLI Bearer tokens issued to users on free-plan organizations can only access a restricted set of endpoints. All other endpoints return a clear upgrade prompt.

**Allowed on free plans:**
- `POST /v1/agent-reports/` — 50 per org per day
- `POST /v1/send-email/` — 20 per org per day
- `GET/POST /v1/agent-messages/`, `POST /v1/agent-messages/read/`
- `GET /v1/agent/health/`
- Agent registration and claim flow
- `GET /v1/me/`, `GET /v1/organization/`, `GET /v1/cli/status/`

**All other endpoints** return:

```json
{
  "detail": "This endpoint requires a paid Dailybot plan. Please upgrade your organization's plan to continue using Dailybot APIs.",
  "code": "plan_upgrade_required",
  "upgrade_url": "https://app.dailybot.com/settings/billing/plans"
}
```

Paid-plan organizations are unaffected. API key transport has its own gates (see [Plan requirements](#plan-requirements) above).

<h2 id="parity-matrix">Authentication method matrix</h2>

> **API keys work on ALL `/v1/` endpoints.** The prior impression that API keys were limited to agent operations was caused by a CLI client-side limitation, not a server-side restriction. This has been corrected as of the Q3 2026 update.

| Endpoint group | API Key | CLI Token | OAuth2 | Notes |
|---------------|:-------:|:---------:|:------:|-------|
| `/v1/me/` | ✅ | ✅ (read) | ✅ | |
| `/v1/organization/` | ✅ | ✅ (read) | — | |
| `/v1/users/` | ✅ | ✅ (read) | — | |
| `/v1/teams/`, members | ✅ | ✅ (read) | — | |
| `/v1/templates/`, `/v1/checkins/` | ✅ | ✅ (read/write) | ✅ | |
| `/v1/forms/` (all operations) | ✅ | ✅ (read/write) | — | |
| `/v1/kudos/` | ✅ | ✅ (read/write) | — | |
| `/v1/kudos/organization/` | ✅ | — | — | Admin only |
| `/v1/workflows/` | ✅ | ✅ (read) | — | Create/update/delete require API key |
| `/v1/workflows/{uuid}/trigger/` | ✅ | ✅ (write) | — | `api_trigger` workflows only; plan-gated |
| `/v1/send-message/` | ✅ | ✅ (write) | — | CLI: role-scoped |
| `/v1/agent-reports/`, health, messages, email | ✅ | ✅ | — | |
| `/v1/cli/updates/`, `/v1/cli/status/` | ✅ | ✅ | — | |
| `/v1/cli/chat/completions/` | ✅ | ✅ (write) | — | AI chat |
| `/v1/cli/auth/status/` | ✅ | ✅ | — | |
| `/v1/cli/auth/logout/` | — | ✅ only | — | Token-scoped |
| `/v1/platform/*` | ✅ | — | — | Exchange token |

## Base URL & versioning

All API endpoints use the following base URL:

```
https://api.dailybot.com/v1/
```

The API is versioned via the URL path. The current version is `v1`. Configure your HTTP client with the full base prefix to ensure forward compatibility.

## Exchange token

The Exchange Token mechanism allows you to make API calls on behalf of other organization members — for example, to give kudos or fill check-in responses in another user's context.

> **Feature disabled by default:** Exchange Token authentication requires explicit enablement. [Contact support](https://app.dailybot.com/forms/86a5b53f-8bc9-4b84-b78f-7c51b805d674/responses/create) with details on your use case.

## Security best practices

- **Save your key immediately** — the full key is only shown once, at creation or regeneration
- **Never commit API keys** to version control or expose them in client-side code
- **Use environment variables** or a secrets manager to store credentials
- **Rotate keys regularly** and immediately revoke any compromised keys
- **Revoke unused keys** from the [Integrations dashboard](https://app.dailybot.com/settings/integrations/api-keys)
- **Use HTTPS only** — all API requests must use TLS encryption
- **Monitor API usage** through the dashboard for unexpected activity

---

## Developer portal navigation

**Getting Started**

- [Overview](/developers)
- [Quick start](/developers/getting-started)
- [Authentication](/developers/authentication) (this page)

**API Reference**

- [API Overview](/developers/api)
- [Users](/developers/api/users)
- [Organization](/developers/api/organization)
- [Teams](/developers/api/teams)
- [Invitations](/developers/api/invitations)
- [Check-ins](/developers/api/check-ins)
- [Forms](/developers/api/forms)
- [Report channels](/developers/api/report-channels)
- [Templates](/developers/api/templates)
- [Kudos](/developers/api/kudos)
- [Mood tracking](/developers/api/mood)
- [Important dates](/developers/api/important-dates)
- [Messaging](/developers/api/messaging)
- [Automations](/developers/api/workflows)
- [Webhooks](/developers/api/webhooks)
- [Commands platform](/developers/api/commands-platform)
- [Agents](/developers/api/agents)
- [OAuth2](/developers/api/oauth2)
- [Integrations](/developers/api/integrations)
- [CLI](/developers/api/cli)

**API guides**

- [Errors & Status Codes](/developers/errors)
- [Rate Limits](/developers/rate-limits)
- [Conventions](/developers/conventions)
- [API Changelog](/developers/api-changelog)
- [Recipes](/developers/recipes)

**Developer Features**

- [Custom commands](/developers/custom-commands)
- [Serverless commands](/developers/serverless)
- [Webhooks & events](/developers/webhooks)
- [Automation API trigger](/developers/workflow-trigger)
- [Activity API](/developers/activity-api)

**CLI**

- [Overview](/developers/cli)
- [Authentication](/developers/cli-authentication)
- [Command reference](/developers/cli-reference)
- [CI/CD recipes](/developers/cli-ci-cd)
- [Configuration](/developers/cli-configuration)
- [Troubleshooting](/developers/cli-troubleshooting)

**Agent Skill**

- [Overview](/developers/agent-skill)
- [Skills catalog](/skills)

---

## Site navigation

**Product:**
- [Home](/)
- [Product](/product)
- [Pricing](/pricing)
- [Enterprise](/enterprise)
- [Integrations](/integrations)
- [Templates](/templates)

**Resources:**
- [Blog](/blog)
- [Academy](/academy)
- [Changelog](/changelog)
- [Help Center](/help)
- [Developers](/developers)
- [Agents](/agents)

**Company:**
- [About](/about)
- [Careers](/careers)
- [Security](/security)
- [Contact Sales](/demo)

**Connect:**
- [LinkedIn](https://www.linkedin.com/company/dailybot/)
- [X/Twitter](https://twitter.com/dailybot)
- [GitHub](https://github.com/Dailybot-Inc)
- [YouTube](https://www.youtube.com/channel/UC3uM9V52vwX7e3vQpCc4qvA)