# Authentication

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:

```http
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:

```javascript
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

1. Create a new key for the project.
2. Deploy the new key to your application.
3. Verify reports arrive with the new key.
4. 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:

```http
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](./examples/nextjs/README.md) 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](./agents.md).

## 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:

```env
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)
```