# Authentication and API keys

Create, use, rotate and revoke API keys.

> **Coming soon:** The Developer API opens soon. You can read the docs now; API keys arrive when it opens.

Every request needs an API key, sent as a bearer token:

```http
Authorization: Bearer pv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## Live and test keys

| Prefix | Mode | What it does |
|---|---|---|
| `pv_live_` | live | Converts your image and uses API credits when the conversion succeeds. |
| `pv_test_` | test | Returns a fixed sample SVG and never uses credits. See [Test mode](/docs/api/test-mode). |

A key is 44 characters: the prefix and 36 letters and digits. The last characters are a checksum,
so a mistyped key is refused at once. Live and test data are separate: a key sees only the
conversions made in its own mode.

## Create a key

Create keys in the [Developers area of your account](/account/developers), while signed in to perfectvector.com. Give each
key a name, for example "Production server", and choose live or test.

- When you create your first key, you accept the [API Terms](/docs/api/terms).
- **We show the key once.** Copy it and store it in a secret manager or an environment variable.
  We keep only a one-way hash, so we cannot show it again. If you lose it, create a new key.
- You can have up to 10 active keys, live and test together. Revoke a key to free its place.
- Keys can be created and revoked only in the Developers area. An API key cannot manage keys.

## Use a key

- Send it only in the `Authorization` header. A key in the URL is ignored, and the request fails
  with `401 invalid_api_key`.
- Call the API from your server or script, never from a web page or a mobile app, where anyone could
  read the key.
- Check which key you are using with `GET /v1/account`. Its `key` object shows the key's name,
  mode, a masked form such as `pv_live_xxxx…xxxx`, and when it was created and last used.

## Rotate a key

1. Create a new key.
2. Deploy it to your systems. Both keys work in the meantime.
3. Revoke the old key.

## Revoke a key

Revoke a key in the Developers area. It stops working within 30 seconds. Revoke a key at once if it
may have leaked: use made with a key before you revoke it is your responsibility. Revoked keys stay
visible in the Developers area for 30 days.

Deleting your PerfectVector account revokes all of its keys.

## Authentication errors

| Status | `code` | Meaning | What to do |
|---|---|---|---|
| 401 | `invalid_api_key` | The key is missing, malformed, unknown or revoked, or its account was deleted. | Check the header and the key. Create a new key if needed. |
| 403 | `account_suspended` | We suspended the account's API access. | Contact us. A new key does not help. |
| 403 | `access_not_granted` | The API is not open to this account yet. The key is valid. | Contact us. Do not rotate the key. |
| 429 | `rate_limited` | Too many failed authentications from your IP address. | Fix the key, then wait the `Retry-After` seconds. |

A `401` answer also carries `WWW-Authenticate: Bearer realm="PerfectVector API"`. All errors are
described in [Errors](/docs/api/errors).

[Site index](https://perfectvector.com/llms.txt) — available pages and descriptions.