Authentication

Token Types

DebugBundle uses three distinct authentication artifacts:

Scope Separation

Project tokens and member tokens serve fundamentally different purposes:

• Project tokens are deployed with your application. They can only write events. If compromised, the attacker can only send noise — they cannot read any data.
• Direct browser project tokens are public write-only keys. For static-only sites, create a dedicated token with allowed browser origins in the dashboard or allowed_origins through API automation to reduce browser-based abuse. Do not reuse that token for server SDKs or relay forwarding, because allowlisted tokens reject requests without a matching Origin. Do not treat the allowlist as a secret boundary because non-browser clients can spoof Origin.
• Member tokens are used by developers and agents. They can read incidents, manage webhooks, create/revoke tokens, and access billing.
• Browser sessions are issued by the web dashboard login flow. They carry the same permissions as member tokens.

Never use a member token as a project token or vice versa. The API rejects the wrong token type at every endpoint.

Using Project Tokens

In the SDK

import DebugBundle from '@debugbundle/sdk-node';

DebugBundle.init({
  projectToken: 'dbundle_proj_xxxxxxxxxxxx',
  environment: 'production',
  service: 'my-api',
});

Direct API Call

curl -X POST https://api.debugbundle.com/v1/events \
  -H "Authorization: Bearer dbundle_proj_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event_id": "evt_001",
        "event_type": "exception",
        "occurred_at": "2025-01-15T10:30:00.000Z",
        "service": { "name": "my-api", "environment": "production" },
        "payload": {
          "type": "TypeError",
          "message": "Cannot read property id of undefined",
          "stacktrace": "..."
        }
      }
    ]
  }'

Response:

{
  "accepted": 1,
  "rejected": 0,
  "errors": []
}

Using Member Tokens

In the CLI

# Interactive chooser
debugbundle login

# Save token to ~/.debugbundle/auth.json
debugbundle login dbundle_mem_xxxxxxxxxxxx

# Or bootstrap the same member-token state through GitHub
debugbundle login --github
debugbundle login --github-cli
debugbundle login --github-device

# All subsequent commands use the saved token
debugbundle incidents
debugbundle inspect inc_abc123

Direct API Call

curl -H "Authorization: Bearer dbundle_mem_xxxxxxxxxxxx" \
  "https://api.debugbundle.com/v1/incidents?limit=10"

With a Custom Auth File

debugbundle incidents --auth-file /path/to/custom/auth.json

Creating Tokens

Via CLI

# Create a project token
debugbundle token project create proj_xxxx --label "production-sdk"

# Create a static-browser token restricted to your site origin
debugbundle token project create proj_xxxx \
  --label "static-browser" \
  --allowed-origin https://www.example.com

# Create an additional member token
debugbundle token member create --label "ci-pipeline"

The plaintext token is shown once at creation. It is never stored or retrievable again.

The first member token can be created in the web app after email-code or GitHub browser sign-in, or bootstrapped directly from the CLI through debugbundle login, GitHub device flow, or an existing gh auth token. In an interactive terminal, plain debugbundle login offers the available bootstrap paths and stores the resulting auth state once complete. After you have one member token, the same identity can create additional member tokens through CLI, API, or MCP-backed workflows.

Via API

# Create a project token
curl -X POST https://api.debugbundle.com/v1/projects/proj_xxxx/tokens \
  -H "Authorization: Bearer dbundle_mem_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "label": "static-browser", "allowed_origins": ["https://www.example.com"] }'

Response:

{
  "token": {
    "token_id": "tok_xxxx",
    "label": "production-sdk",
    "allowed_origins": ["https://www.example.com"],
    "token_preview": "dbundle_proj_xxxx...xxxx",
    "plaintext": "dbundle_proj_full_token_shown_once",
    "created_at": "2025-01-15T10:30:00.000Z"
  }
}

Via Dashboard

Navigate to Project → Tokens to create and manage project tokens through the web interface. For static-only browser sites, fill Allowed browser origins when creating the token; enter one origin per line or comma-separated. The API stores those values as allowed_origins.

Token Storage

Security

• Tokens are hashed at rest (SHA-256). The API stores only the hash.
• The plaintext is shown once at creation and never again.
• Tokens can be revoked immediately via CLI, API, or dashboard.
• Token previews (first/last 4 characters) are available for identification.

Browser Sessions

Browser sessions are created by the web dashboard's login flow.

Email Code Login

curl -X POST https://api.debugbundle.com/v1/auth/request-code \
  -H "Content-Type: application/json" \
  -d '{ "email": "dev@example.com", "accepted_terms": true }'

Then verify the one-time code to create the browser session:

curl -X POST https://api.debugbundle.com/v1/auth/verify-code \
  -H "Content-Type: application/json" \
  -d '{ "email": "dev@example.com", "code": "123456" }'

GitHub OAuth

The dashboard redirects to GitHub for authentication and completes via the callback endpoint. No manual API call needed.

GitHub CLI Bootstrap

For headless or agent workflows, DebugBundle also supports two CLI bootstrap paths that both end by issuing a normal member token:

• debugbundle login --github-device starts GitHub device flow and shows a browser URL plus short code.
• debugbundle login --github-cli exchanges an already-authenticated gh auth token with DebugBundle.
• debugbundle login offers these same choices interactively when run in a TTY without explicit auth flags.

Session Cookie

After login, the API sets an HTTP-only dbundle_session cookie. The dashboard sends this cookie with every request. The session payload also includes auth_methods.email, auth_methods.github, and a csrf_token for browser-session mutations. Browser sessions carry the same permissions as a member token.

Verifying Authentication

CLI

debugbundle whoami

Output:

Authenticated: yes
Base URL: https://api.debugbundle.com
Auth File: ~/.debugbundle/auth.json
Token: dbundle_mem_xxxx...xxxx

API

Every authenticated endpoint returns 401 with { "error": "invalid_member_token" } or { "error": "invalid_project_token" } if authentication fails. There is no separate "whoami" API endpoint — use any list endpoint to verify.

Next Steps

• API Overview — Full endpoint index and response format
• Incidents API — Query and manage incidents