Authentication
Authenticate ScreenFramed API requests with bearer tokens, scoped API keys, and signed URLs.
Most API requests use a ScreenFramed API key in the Authorization header.
bashAuthorization: Bearer sf_live_...
API key environments
| Environment | Prefix | Behavior |
|---|---|---|
| Live | sf_live_... | Renders are billed against your account credits. |
| Test | sf_test_... | Useful for integration testing. Test mode skips credit debits where supported by the capture pipeline. |
Scopes
API keys can be scoped. A key with no explicit scope list behaves like a full-access key for the current API surface.
| Scope | Allows |
|---|---|
capture | Create styled captures through /v1/capture. |
raw | Create raw browser screenshots through /v1/raw. |
jobs | Read async job status. |
usage | Read credit and render usage. |
projects | Manage projects and signing secrets. |
auth_profiles | Manage authenticated capture profiles. |
renders | Access render resources used by dashboard flows. |
Use separate keys for CI, production, local development, and customer-facing signed URL generation. Revoke keys that are no longer needed.
Query-string key fallback
The API can read api_key from the query string, but use bearer auth whenever possible. Query strings are easier to leak through logs, browser history, analytics, and referrers.
bashcurl "https://screenframed.com/v1/capture?site=example.com&api_key=$SCREENFRAMED_API_KEY"
Signed URLs
Signed URLs let you create render links without exposing an API key. They are project-scoped, time-limited, and validated using your project signing secret.
Use signed URLs for:
- User-triggered image generation in a browser.
- Embeddable templates where an API key would be unsafe.
- Workflows where a backend can mint a short-lived URL and the client can fetch it directly.
See Signed URLs for canonicalization and examples.
Authenticated page capture
API authentication is separate from logging into the page being captured. To capture an internal dashboard or app state, create an auth profile and pass auth_profile_id in the capture request.