# Authentication

> How to pass your API key to the REST API and signed database download endpoints.

API keys are created and managed in the [dashboard](https://dashboard.ipscope.io). Live keys start with `ips_live_` so secret scanners in GitHub and CI pipelines can detect accidental commits immediately.

## Three ways to send a key

Send the key in the `Authorization` header, the `X-API-Key` header, or the `key` query parameter. All three are accepted on every authenticated endpoint.

```bash Authorization header (recommended)
curl -sS https://api.ipscope.io/v1/ip/198.51.100.7 \
  -H "Authorization: Bearer ips_live_••••••••"
```

```bash X-API-Key header
curl -sS https://api.ipscope.io/v1/ip/198.51.100.7 \
  -H "X-API-Key: ips_live_••••••••"
```

```bash Query parameter
curl -sS "https://api.ipscope.io/v1/ip/198.51.100.7?key=ips_live_••••••••"
```

> **Tip:** Prefer `Authorization: Bearer` or `X-API-Key` in production. Query parameters are often recorded in proxy access logs and APM traces.

## Using keys with Official Server SDKs

All 8 [official server SDKs](https://ipscope.io/docs/sdks) accept an explicit `apiKey` / `api_key` parameter and automatically send `Authorization: Bearer` and `X-API-Key` headers on every request:

```python Python
from ipscope import AsyncIpScopeClient

client = AsyncIpScopeClient(api_key=os.environ["IPSCOPE_KEY"])
```

```ts Node.js
import { IpScopeClient } from '@ipscope/sdk-node';

const client = new IpScopeClient({ apiKey: process.env.IPSCOPE_KEY });
```

```go Go
client := ipscope.NewClient(ipscope.Config{APIKey: os.Getenv("IPSCOPE_KEY")})
```

## Keeping keys on the server

> **Warning:** API keys are designed for server-side backends, edge workers and cron jobs. Do not embed a live API key in browser JavaScript or mobile binaries.

## Rotating a key without downtime

- Create a second key in the dashboard (`Settings → API Keys`).
- Deploy the new key to your servers and verify traffic in the usage graph.
- Revoke the old key. Revocation takes effect globally within 30 seconds.

## When authentication fails

| Status | Code | Cause |
| --- | --- | --- |
| `401` | `missing_api_key` | No key was sent on an endpoint that requires authentication. |
| `401` | `invalid_api_key` | The key does not exist or has been revoked. |
| `403` | `forbidden_field_family` | The request asked for a field family outside the key’s plan tier. |