# Authentication

DocuShell uses bearer authentication for every public API route. API keys are the production path today; JWT bearer tokens are documented as a gateway-compatible pattern for future account-scoped integrations.

Source: https://docs.docushell.com/authentication
Category: Authentication
Read time: 4 min

## Related

- [Public API Gateway](/public-api-gateway.md): See the base URL, request envelope, response format, and gateway responsibilities.
- [Error Codes](/error-codes.md): Review the auth and permission failures returned by the gateway.

## Summary

| Label | Value | Description |
| --- | --- | --- |
| Header | Authorization | Send a bearer credential on every submit, status, and download route. |
| Primary Method | API Key | Create keys in the DocuShell dashboard and keep them in server-side environments. |
| Retry Safety | Idempotency-Key | Use a stable key when retrying the same queued job after a timeout. |

## API Keys

API keys are the recommended production authentication method for DocuShell API clients. Generate them in the dashboard, store them in a secret manager, and attach them as bearer tokens.

Do not ship API keys in browser bundles. DocuShell is browser-based for end users, but API credentials belong in server-side code, workers, CI systems, or trusted automation runtimes.

- Use `Authorization: Bearer YOUR_API_KEY` on every route.
- Rotate exposed keys from the dashboard.
- Pair submit requests with `Idempotency-Key` when callers may retry.

## Auth Headers

### API key header

```http
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: job-submit-001
```

### JWT bearer header

```http
Authorization: Bearer YOUR_JWT
```

JWT bearer tokens use the same header shape. Treat them as account-scoped gateway credentials only where your deployment explicitly supports them.

## Authentication Methods

| Method | Status | Use case |
| --- | --- | --- |
| API Key | Recommended | Server-side integrations, workers, automation, and backend services. |
| JWT | Gateway-compatible / deployment-dependent | Session or account-scoped integrations where the deployment issues JWT bearer tokens. |
| Anonymous | Not supported | Public docs and health checks can be browsed, but API work requires credentials. |

## Idempotent Retries

Queued PDF work can be expensive, so submit routes accept `Idempotency-Key`. If a client times out before receiving the queued response, retry the exact same request with the same idempotency key.

If the payload changes, create a new idempotency key. The gateway returns a conflict when the same key is reused for different work.