---
title: Authentication | Plaza Docs
description: API keys, rate limits, and security best practices for the Plaza API.
---

Every request to Plaza requires an API key. You can pass it in any of three ways:

1. **`X-API-Key` header** (recommended):

Terminal window

```
curl https://plaza.fyi/api/v1/features?around=48.85,2.34&radius=500 \
  -H "x-api-key: pk_live_abc123"
```

2. **`Authorization: Bearer` header:**

Terminal window

```
curl https://plaza.fyi/api/v1/features?around=48.85,2.34&radius=500 \
  -H "Authorization: Bearer pk_live_abc123"
```

3. **`api_key` query parameter** (not recommended for production — keys may appear in logs):

Terminal window

```
curl "https://plaza.fyi/api/v1/features?around=48.85,2.34&radius=500&api_key=pk_live_abc123"
```

All SDK clients accept the key at initialization:

```
import Plaza from "@plazafyi/sdk";


// Reads PLAZA_API_KEY from environment automatically
const client = new Plaza();


// Or pass explicitly
const client = new Plaza({ apiKey: "pk_live_abc123" });
```

```
import plaza


# Reads PLAZA_API_KEY from environment automatically
client = plaza.Client()


# Or pass explicitly
client = plaza.Client(api_key="pk_live_abc123")
```

```
import "github.com/plazafyi/plaza-go"


// Reads PLAZA_API_KEY from environment automatically
client := plaza.NewClient()


// Or pass explicitly
client := plaza.NewClient(plaza.WithAPIKey("pk_live_abc123"))
```

## API key format

Keys are prefixed `pk_live_` for production and `pk_test_` for sandbox. The prefix indicates the environment — there’s no other difference.

## Getting a key

Sign up at [plaza.fyi](https://plaza.fyi) and grab a key from the dashboard. Free accounts get a key immediately. No credit card required.

## Rate limits

Rate limits are per account (shared across all keys for the same user), enforced with a sliding window.

| Plan       | Requests/min | Included                          | Price   |
| ---------- | ------------ | --------------------------------- | ------- |
| Free       | 10           | 500 standard/day + 10 premium/day | $0      |
| Pro 100K   | 300          | 100,000/month                     | $50/mo  |
| Pro 300K   | 1,000        | 300,000/month                     | $150/mo |
| Pro 1M     | 2,000        | 1,000,000/month                   | $500/mo |
| Enterprise | 10,000       | Custom                            | Custom  |

The free tier has a hard daily cap: 500 standard requests and 10 premium requests per day, resetting at midnight UTC. Once you hit the limit, requests return `429 daily_limit_exceeded` until the next reset. No surprise bills.

Standard on-demand overage for Pro plans is $0.50 per 1,000 requests.

### Premium endpoints

Routing, isochrone, distance matrix, map matching, route optimization, elevation, and nearest-snap endpoints count as **4x** against your monthly allocation. A single routing request uses 4 of your included requests. Rate-per-minute limits are unaffected — only the monthly count multiplies.

Premium on-demand overage is $1.50 per 1,000 requests.

### Rate limit headers

Every response includes these headers:

```
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
```

When you hit the limit, you get a `429` with a `Retry-After` header (in seconds). Respect it.

## Key rotation

You can have up to 3 active keys per account. The intended workflow for rotation:

1. Create a new key in the dashboard.
2. Deploy it to your application.
3. Verify traffic is flowing on the new key.
4. Revoke the old key.

Old and new keys work simultaneously until you revoke one.

## Security

**Do not ship your API key in client-side code.** Plaza keys are secret. If you need to call Plaza from a browser, proxy through your own backend.

- Store keys in environment variables or a secrets manager, never in source code.
- Use separate keys for staging and production.
- Rotate keys if you suspect a leak. Revocation is instant.
- Monitor usage on the dashboard. Unusual spikes may indicate a compromised key.

If a key is compromised, revoke it immediately from the dashboard. There’s no undo — revoked keys stop working within seconds.