# Authentication

Authenticate API requests with a Browsable API key and use task metadata to discover live
			pricing and schema information.

## API Keys

All API requests require a Bearer token in the `Authorization`
header:

```bash
curl -X POST "https://api-ingress-worker-staging.browsable-staging.workers.dev/v1/reddit/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"test","_run":{"async":false}}'
```

## Getting an API Key

- Sign up for a Browsable account at [browsable.app](https://browsable.app) .

- Open the API Keys page in your dashboard.

- Create a key and store it securely.

### Security Best Practices

- Never commit API keys to version control.

- Store keys in environment variables or a secret manager.

- Rotate keys regularly.

- Revoke compromised keys immediately.

## Optional Idempotency

For `POST` endpoints that create work, you can optionally send an
`Idempotency-Key` header. When you
			retry the same request with the same key, Browsable can return the original run or generation
			instead of creating duplicate work.

```bash
curl -X POST "https://api-ingress-worker-staging.browsable-staging.workers.dev/v1/reddit/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: req_123" \
  -d '{"query":"test"}'
```

## Managing API Keys

You can manage your API keys using the Admin API endpoints:

### List API Keys

```bash
curl -X GET "https://api-ingress-worker-staging.browsable-staging.workers.dev/admin/list-keys" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Create New API Key

```bash
curl -X POST "https://api-ingress-worker-staging.browsable-staging.workers.dev/admin/create-key" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Revoke API Key

```bash
curl -X POST "https://api-ingress-worker-staging.browsable-staging.workers.dev/admin/revoke-key" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key_id": "key_abc123"}'
```

## Credits And Rate Limits

- Task pricing is exposed live via `/v1/tasks` and `/v1/tasks/{task_key}` in the `credit_cost` field.

- Different tasks can cost different amounts.

- Rate limits and entitlement checks are enforced at request time. A `429` means you should retry with backoff. A `403` usually means your account cannot execute the task.

## Error Responses

API-level failures use a structured problem-details style response. Examples:

### 401 Unauthorized

```json
{
  "type": "https://api-ingress-worker-staging.browsable-staging.workers.dev/problems/http-401",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Missing or invalid API key",
  "error": "Missing or invalid API key",
  "request_id": "req_abc123",
  "error_code": null,
  "retryable": null,
  "action": null
}
```

### 403 Forbidden

```json
{
  "type": "https://api-ingress-worker-staging.browsable-staging.workers.dev/problems/http-403",
  "title": "Forbidden",
  "status": 403,
  "detail": "Your account cannot execute this task.",
  "error": "Your account cannot execute this task.",
  "request_id": "req_def456",
  "error_code": null,
  "retryable": null,
  "action": null
}
```

### 429 Rate Limit Exceeded

```json
{
  "type": "https://api-ingress-worker-staging.browsable-staging.workers.dev/problems/http-429",
  "title": "Rate limited",
  "status": 429,
  "detail": "Rate limit exceeded. Please try again later.",
  "error": "Rate limit exceeded. Please try again later.",
  "request_id": "req_xyz789",
  "error_code": null,
  "retryable": null,
  "action": null
}
```

### Need higher limits?

Contact us about higher throughput, custom quotas, or dedicated support.

 [Contact Sales](https://browsable.app/support)

---
Source: https://browsable-api-ux-staging.pages.dev/docs/guides/authentication