BugTape docs

Authentication

Capture keys, sessions and agent tokens.

BugTape uses project capture keys for SDK ingestion, user JWT tokens for the console, and scoped agent tokens for agent access. Keep these credentials separate.

API keys (SDK and ingestion)

API keys authenticate bug report submissions. They are scoped to a single project.

Key format

bt_live_<32-char random string>   # Production key
bt_test_<32-char random string>   # Test/staging key

Keys are generated via the console or the POST /v1/projects/:id/keys endpoint.
The full key is shown once at creation time. BugTape stores only a bcrypt hash.
Keys are identified by their 8-character prefix (bt_live_ or bt_test_).

Using an API key

Pass the key in the X-BugTape-Key header:

POST /v1/ingest HTTP/1.1
Host: app.bugtape.ai
Content-Type: application/json
X-BugTape-Key: bt_live_abcdefghijklmnopqrstuvwxyz123456

{ "title": "Button doesn't work", ... }

Or with the SDK:

import { init } from 'https://app.bugtape.ai/bugtape.mjs';
init({ apiKey: 'bt_live_abcdefghijklmnopqrstuvwxyz123456' });

Key types

Prefix	Purpose	Browser-safe?	Notes
`bt_live_`	Production ingestion	Yes	Rate-limited, plan-enforced
`bt_test_`	Development/staging	Yes	Same behavior, separate namespace

Both key types are browser-safe. API keys authorize bug report submission only — they cannot read bugs, manage projects, or access other data. They are designed to be embedded in client-side JavaScript.

Key management

Action	Endpoint	Auth
Create key	`POST /v1/projects/:id/keys`	JWT
List keys	`GET /v1/projects/:id/keys`	JWT
Revoke key	`DELETE /v1/projects/:id/keys/:keyId`	JWT

Listed keys show only the prefix, label, and last_used timestamp — never the full key.

Key rotation

Create a new key for the project.
Deploy the new key to your application.
Verify reports arrive with the new key.
Revoke the old key.

There is no automatic rotation. Multiple active keys per project are supported, so you can rotate without downtime.

JWT tokens (console and management API)

Console users authenticate with email/password and receive JWT tokens.

Access token: 1 hour expiry, passed as Authorization: Bearer <token>.
Refresh token: 30 days expiry, used to obtain new access tokens via POST /v1/auth/refresh.

JWT tokens are required for all management operations (listing bugs, updating status, managing team, etc.).

Organization scoping

All management API requests require the X-BugTape-Org header with the organization UUID:

GET /v1/bugs HTTP/1.1
Authorization: Bearer eyJ...
X-BugTape-Org: 550e8400-e29b-41d4-a716-446655440000

This prevents cross-tenant data access. The server verifies the user is a member of the specified organization.

Roles

Role	Capabilities
`admin`	Full access: manage team, projects, settings, integrations
`manager`	Manage bugs, projects, view team
`member`	View and update bugs, add comments
`viewer`	Read-only access to bugs and projects

Browser-direct vs backend-proxied ingestion

Browser-direct (recommended for most apps)

The SDK submits reports directly from the browser to https://app.bugtape.ai/v1/ingest. This is the default and recommended approach.

Browser → BugTape API

Advantages:

Simple setup through the hosted browser ES module; the npm package is not currently published.
No backend changes required.
API keys are browser-safe (ingest-only permissions).

When to use: Most web applications, SPAs, static sites.

Backend-proxied

Your server receives the report from the browser and forwards it to BugTape. Useful when you need to enrich reports with server-side data or enforce additional access control.

Browser → Your Backend → BugTape API

When to use:

You want to attach server-side metadata (tenant ID, feature flags, etc.).
Corporate firewall blocks direct access to app.bugtape.ai.
You want to validate or filter reports before forwarding.

See Next.js integration guidance for a browser-first setup and proxy requirements.

Capture keys and agent tokens

Project capture keys do not grant access to existing reports or workspace administration. They can still submit data and consume project quotas; rotate a leaked key and monitor its use. Separate binary-evidence upload authorization is not implied by the structured ingest key.

Agent tokens (bt_pat_*) carry scopes and project grants. They belong in the agent client or server, never in the browser SDK. MCP access requires the relevant plan. See agent setup.

Environment variables

Variable	Required	Description
`BUGTAPE_API_KEY`	Yes	Your project API key (`bt_live_` or `bt_test_`)
`BUGTAPE_ENDPOINT`	No	Full ingest endpoint passed by your integration (default: `https://app.bugtape.ai/v1/ingest`)

These are integration configuration names, not automatic SDK configuration. Your code must pass the selected key and endpoint to init. In Next.js, only capture keys and non-secret configuration belong in NEXT_PUBLIC_* variables:

NEXT_PUBLIC_BUGTAPE_API_KEY=bt_live_xxx
NEXT_PUBLIC_BUGTAPE_ENDPOINT=https://app.bugtape.ai/v1/ingest
BUGTAPE_API_KEY=bt_live_xxx          # Server-side proxy key (if using proxy)