Tokens

DebugBundle uses three types of authentication tokens, each with a distinct scope and purpose. Tokens are never stored in plaintext — they are hashed before persistence and shown only once at creation time.

Token Types

Project Tokens

Project tokens are write-only. They allow SDKs to send events to a specific project but cannot read data, list incidents, or perform any management operations.

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

DebugBundle.init({
  projectToken: 'dbundle_proj_a1b2c3d4e5f6...',
});

Project tokens are scoped to a single project. You can create multiple tokens per project for different environments or services.

Browser SDK deployments should use a backend relay when a backend is available, so the project token stays server-side. Same-origin relay paths are simplest; split frontend/backend apps can use explicit browser relay mode with relay preflight handling and relay allowedOrigins. Static-only sites may embed a dedicated public write-only project token and set allowed browser origins in the dashboard, CLI, API, or MCP. Allowlisted tokens reject ingestion and SDK config requests without a matching Origin, so they should not be reused for server SDKs or relay forwarding. The allowlist blocks normal browser requests from other origins, but non-browser clients can spoof Origin, so it does not make the token secret.

Member Tokens

Member tokens provide read and manage access. They are used for:

• CLI commands (debugbundle CLI)
• Direct API calls
• MCP tool invocations

# CLI authentication
export DEBUGBUNDLE_TOKEN=dbundle_mem_x9y8z7w6v5u4...

# API call
curl https://api.debugbundle.com/v1/projects \
  -H "Authorization: Bearer dbundle_mem_x9y8z7w6v5u4..."

Member tokens can access all projects within the member's organization scope.

Probe Trigger Tokens

Probe trigger tokens are single-purpose request/session triggers returned when a member-token-authenticated probe activation is created. They are designed for CI/CD pipelines and automation where you need to request richer probe data for a targeted request without granting broader API access.

# First create a remote activation with a member token.
curl -X POST https://api.debugbundle.com/v1/projects/proj_01HXYZ/probes/activate \
  -H "Authorization: Bearer dbundle_mem_x9y8z7w6v5u4..." \
  -H "Content-Type: application/json" \
  -d '{
    "label_pattern": "payment.*",
    "service": "payments",
    "environment": "staging",
    "ttl_seconds": 300,
    "trigger_ttl_seconds": 3600
  }'

# Then attach the returned trigger token to the request you want enriched.
curl https://payments.example.internal/checkout \
  -H "X-DebugBundle-Probe-Trigger: dbundle_probe_m3n4o5p6q7r8..."

Token Security

Hashing at Rest

All tokens are hashed with SHA-256 before storage. The plaintext token is returned exactly once — at creation time. DebugBundle cannot recover a lost token; you must create a new one.

Creation response:
{
  "token": "dbundle_mem_x9y8z7w6v5u4...",    ← shown once
  "token_id": "tok_01HXYZ...",
  "created_at": "2025-01-15T10:30:00Z"
}

Stored in database:
{
  "token_id": "tok_01HXYZ...",
  "token_hash": "a3f2b1c0d9e8f7...",          ← SHA-256 hash
  "prefix": "dbundle_mem_"
}

Password Hashing

User account passwords use Argon2 (not SHA-256), providing stronger protection against brute-force attacks.

Creating Tokens

CLI

# Create a project token
debugbundle token project create proj_01HXYZ... --label "Production SDK"

# Create a static-browser project token with an origin allowlist
debugbundle token project create proj_01HXYZ... \
  --label "Static browser" \
  --allowed-origin https://www.example.com

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

The first member token is usually created from the web app after email-code or GitHub browser sign-in, or bootstrapped through debugbundle login, --github, --github-cli, or --github-device. Probe trigger tokens are returned by probe activation, for example debugbundle probe activate ... --trigger-ttl-seconds ...; they are not bearer auth tokens for the probe-management API.

API

# Create a project token
curl -X POST https://api.debugbundle.com/v1/projects/proj_01HXYZ.../tokens \
  -H "Authorization: Bearer dbundle_mem_..." \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Production SDK"
  }'

# Create an additional member token
curl -X POST https://api.debugbundle.com/v1/member/tokens \
  -H "Authorization: Bearer dbundle_mem_..." \
  -H "Content-Type: application/json" \
  -d '{
    "label": "CI pipeline"
  }'

MCP

Create a project token for project proj_01HXYZ named "Production SDK"

The MCP tools handle token creation conversationally through create_project_token and create_member_token tools.

Token Rotation

Rotate tokens without downtime by overlapping old and new tokens:

1. Create new token — Generate a replacement before revoking the old one.
2. Deploy new token — Update SDKs, CI/CD, and CLI configurations.
3. Verify traffic — Confirm events are arriving with the new token.
4. Revoke old token — Remove the previous token.

# List tokens to find the one to rotate
debugbundle token project list proj_01HXYZ...

# Create replacement
debugbundle token project create proj_01HXYZ... --label "Production SDK v2"

# After deploying the new token, revoke the old one
debugbundle token project revoke proj_01HXYZ... tok_01HOLD...

Scope Enforcement

Token scopes are enforced at the API gateway level:

Best Practices

1. Use the narrowest scope — Prefer project tokens for SDKs. Never embed member tokens in client-side code.

2. Name tokens descriptively — Include the environment and purpose: "Production API Server", "Staging CI Pipeline".

3. Rotate on team changes — When a team member leaves, rotate any member tokens they had access to.

4. One token per context — Create separate project tokens for each environment/service pair. This lets you revoke access granularly.

5. Store securely — Use environment variables or secret managers. Never commit tokens to source control.

Next Steps

• Redaction — Automatic sensitive data removal
• CLI Token Management — Detailed CLI token commands
• API Authentication — API auth headers and patterns