Authentication

Every request to the API needs an API key. This page explains the header format, how to create a key, and how to rotate one.

The API key header

Send the key as a bearer token in the Authorization header. Keys start with pv_live_.

curl https://api.provenance.pixellab.nz/v1/detect \
  -H "Authorization: Bearer pv_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photo.jpg"}'

If the header is missing or the key is wrong, the API returns HTTP 401 with the error type authentication_error. Read the errors page for the response format.

Create a key

1. Sign in at the sign in page. We send a sign in link to your email. There is no password.
2. Open the dashboard. On your first visit, the dashboard creates a key named "Default" and shows it once.
3. To add a key, enter a name and select "Create key". Use one key per application or environment, so you can revoke one without the others.

We store the SHA-256 hash of each key and the first characters of the key. We never store the key itself, so the dashboard cannot show a key after you close the panel.

You can have at most 10 active keys.

Rotate a key

1. Create a new key in the dashboard.
2. Update your application to send the new key.
3. Revoke the old key. Requests that use a revoked key fail at once with HTTP 401.

If you think a key has leaked, revoke it first and create a new one after.

Keep the key safe

• Store the key in an environment variable or a secrets manager, not in source code.
• Send requests from a server. If you call the API from a browser or a mobile application, anyone who opens the application can read the key.
• Every key shares the quota of your account. Read the rate limits page.