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

# Authentication
URL: /developers/docs/papers-api/authentication
LLM index: /llms.txt
Description: Use sxv_ API keys with Bearer or x-api-key header. Keys are validated against your live subscription.

# 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 you may have
   - Hourly rate limit (shared across **all** your keys)
   - Maximum results per request (100 on all plans)

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).