# API key handling

The Site-Shot screenshot API key is a long-lived operational secret used by `https://api.site-shot.com/`.

Generic profile, subscription, and usage endpoints never return the full key. They may return a masked representation for identification.

Use `POST /api/v1/agent/reveal-api-key/` with the `api_key:read` scope to reveal the key. The response includes a warning, an audit log id, and two dashboard links: `dashboard_url` and `reset_url`, which is the page carrying the reset button. There is no URL that rotates the key on its own — rotation is a form submission with a CSRF token, so it cannot be done with an OAuth token. Send the user to `reset_url` and have them press it.

The key becomes active only after the account confirms its email address. Until then this endpoint returns `403` with `Email confirmation is required before the API key is active.` — tell the user to open the confirmation link Site-Shot emailed them, then retry. Do not treat that 403 as an authorization problem with the OAuth token.

If the key is exposed, the user should reset it from the Site-Shot dashboard.