PerfectVectorAuthentication and API keys
Create, use, rotate and revoke API keys.
The Developer API opens soon. You can read the docs now; API keys arrive when it opens.
On this page
Every request needs an API key, sent as a bearer token:
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. |
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, 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.
- 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
Authorizationheader. A key in the URL is ignored, and the request fails with401 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. Itskeyobject shows the key's name, mode, a masked form such aspv_live_xxxx…xxxx, and when it was created and last used.
Rotate a key
- Create a new key.
- Deploy it to your systems. Both keys work in the meantime.
- 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.