---
title: "Authentication"
description: "Use sxv_ API keys with Bearer or x-api-key header. Keys are validated against your live subscription."
canonical_url: "https://scholarxiv.com/developers/docs/papers-api/authentication"
markdown_url: "https://scholarxiv.com/developers/docs/papers-api/authentication.md"
---

> For the complete documentation index, see [llms.txt](/llms.txt).

# Authentication

All Papers API requests require a ScholarXIV API key.

## Headers

```http title="Recommended"
Authorization: Bearer sxv_your_key_here
```

```http title="Alternative"
x-api-key: sxv_your_key_here
```

Keys always start with `sxv_`.

## How Keys + Subscriptions Work Together

1. The key is validated using secure hashing (via better-auth).
2. On **every single request** we look up your **current active subscription** (the same plan that powers the web app).
3. We apply the entitlements for that plan:
   - Maximum number of keys: Free 2, Plus 5, Pro 20
   - Hourly rate limit: Free 1,200/hour, Plus 2,400/hour, Pro 3,600/hour (shared across **all** your keys)
   - Maximum results per request (Free 2,000, Plus 4,000, Pro 6,000)

Limits are always evaluated live at request time.

See the [Rate Limits & Quotas](/developers/docs/papers-api/limits) page for the full entitlements table, rolling window details, downgrade behavior, and 429 handling.

> [!TIP]
> Your dashboard always shows the live numbers from your current subscription.

## Creating & Managing Keys

Create keys only from the [Developer Dashboard](/developers/dashboard/apikeys).

- Name them clearly.
- Set a realistic expiration (or "Never" for long-running services).
- The raw key is shown **once**. Store it in an environment variable immediately:

```txt title=".env"
SCHOLARXIV_API_KEY=sxv_...
```

**Best practices**

- One key per service or environment.
- Rotate keys periodically (create new → update service → delete old).
- Never log the full key. Log only the prefix (`sxv_abc...`) when needed for debugging.
- Never embed keys in client-side JavaScript, mobile apps, or public repos.

## Errors During Authentication

| Status | Message                                            | Likely Cause                                                   |
| ------ | -------------------------------------------------- | -------------------------------------------------------------- |
| 401    | `API Key is required`                              | Missing header                                                 |
| 401    | `Invalid API key format. Should start with 'sxv_'` | Wrong token type                                               |
| 401    | `Invalid API key`                                  | Revoked, expired, or never existed                             |
| 429    | `Rate limit exceeded`                              | See [Rate Limits & Quotas](/developers/docs/papers-api/limits) |

## Security Checklist

- Load keys only from server environment variables.
- Use different keys for dev/staging/prod.
- Rotate keys on any suspected exposure.
- Prefer short-lived keys for anything that can be rotated automatically.
- Build a thin server-side proxy/wrapper so browser or mobile clients never see the real key.

> [!TIP]
> A small server wrapper also lets you add caching, logging, and per-user quotas on top of the Papers API without exposing secrets.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).