> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rushed.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with the Rushed API using API keys — scopes, expiration, rotation, and best practices.

## API Key authentication

Every request to the Rushed API requires an API key sent via the `X-API-Key` header.

```bash theme={null}
curl https://worker.rushed.com.br/api/articles \
  -H "X-API-Key: rsh_live_xxxxxxxxxxxxxxxxxxxx"
```

## Getting your API key

1. Sign in to the [Rushed Dashboard](https://dash.therushed.com.br)
2. Navigate to **API Keys**
3. Click **Create Key**
4. Configure the key name, expiration, and scopes
5. Copy the key — it will only be shown once

## Key format

| Prefix      | Environment | Usage                                      |
| ----------- | ----------- | ------------------------------------------ |
| `rsh_live_` | Production  | Live data, counted against your plan quota |
| `rsh_test_` | Sandbox     | Test data, not counted against quota       |

## Key scopes

When creating an API key, you can restrict its access to specific resources:

| Scope           | Access                              |
| --------------- | ----------------------------------- |
| `read:articles` | List, search, and retrieve articles |
| `read:entities` | List, search, and retrieve entities |
| `read:breaking` | Access breaking news endpoint       |
| `*`             | Full access (all scopes)            |

A key with no explicit scopes defaults to `*` (full access within your plan tier).

## Key expiration

You can set an expiration when creating the key:

* **No expiration** — key is valid until manually revoked
* **Custom duration** — 30 days, 90 days, 1 year, or a specific date
* Expired keys return `401 Unauthorized`

## Rate limits by plan

Rate limits are enforced per API key:

| Plan         | Requests / month | Requests / minute |
| ------------ | ---------------: | ----------------: |
| **Starter**  |          500,000 |               100 |
| **Pro**      |        3,000,000 |               500 |
| **Business** |        Unlimited |             2,000 |

See [Rate Limits](/guides/rate-limits) for details on headers and backoff strategies.

## Key rotation

To rotate a key without downtime:

1. Create a new key in the dashboard
2. Update your application to use the new key
3. Verify the new key works
4. Revoke the old key

<Warning>
  Never commit API keys to source control. Use environment variables or a secrets manager.
</Warning>

## Error responses

| Status | Meaning                                                                                  |
| ------ | ---------------------------------------------------------------------------------------- |
| `401`  | Missing, invalid, or expired API key                                                     |
| `403`  | Key does not have the required scope, or your plan does not include the requested module |
| `429`  | Rate limit exceeded                                                                      |

```json theme={null}
{
  "success": false,
  "error": "Invalid or missing API key. Get your key at https://dash.therushed.com.br/api-keys",
  "statusCode": 401
}
```