Tokens

DebugBundle uses distinct application token types plus a separate OAuth credential family, each with a distinct scope and purpose. Application bearer tokens are hashed before persistence and shown only once at creation time; OAuth provider artifacts follow a separate encrypted storage path.

Token Types

OpenAI OAuth credentials

The OpenAI Plugin candidate does not reuse member or project tokens. Linking uses OAuth/OIDC with PKCE S256, exact redirects, RFC 9207 authorization-response issuer behavior, Client ID Metadata Document validation, and authenticated client assertions. Access tokens are bound to https://mcp.debugbundle.com, expire after 12 minutes, and contain no email. Verified identity is read from UserInfo only when account/workspace policy needs it.

Refresh tokens expire after 30 days and rotate on use. Reuse revokes the token family. Authorization codes expire after 5 minutes and are single-use. Revoking a grant, deleting/suspending the account, or losing required membership stops access. The stdio MCP package and CLI retain their existing member-token and local-auth behavior.

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.

Restricted agent read credentials

An owner or project admin can create a separate credential for one project. It expires after 30 days by default (maximum 90 days), can be revoked, and stops working if its issuer loses project access. It can list minimized incidents and retrieve existing bounded context or bundles. It cannot request raw logs, bodies, direct object downloads, regeneration, or management operations. The general member-connected CLI/MCP remains a broader connection.

debugbundle token agent create <project-id> --label "coding agent"
# Copy the plaintext shown once into a protected secret store.
DEBUGBUNDLE_AGENT_TOKEN=<credential> debugbundle agent connect
debugbundle agent list_incidents <project-id>

# In a separate MCP configuration, run:
debugbundle-mcp --agent-read

The restricted CLI profile lives at ~/.debugbundle/agent-auth.json with owner-only file permissions and does not use the member login. --agent-read advertises exactly five read tools and rejects direct calls to other tools. For self-hosting, set DEBUGBUNDLE_API_URL for MCP or pass --base-url to the CLI. Older API versions reject this token type. Creation remains unavailable until the additive database migration and every serving replica are updated; the operator then explicitly sets AGENT_TOKEN_ISSUANCE_ENABLED=true on the API fleet.

The returned evidence is minimized using field allowlists and credential scrubbing; it cannot identify every confidential fact or prevent malicious instructions in customer text from influencing the receiving agent. Review capture settings and what the provider receives.

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

Dashboard agent credential management

Project owners/admins can list, create and revoke scoped agent credentials in the project Tokens tab. Issuance stays disabled by default on the server, and unavailable creation is explicit. Optional UTC expiry must be in the future and within 90 days; omission uses the server's 30-day default. A successful creation reveals plaintext once. Ordinary lists and revoke responses never reveal the credential secret.