API key setup
Every request is authenticated with a bearer API key tied to your account and its credit balance.
Create a key
Go to Dashboard → API keys and create a key. Keys start with usk_ and the full value is shown exactly once, at creation. We store only a hash, so it cannot be recovered later. If a key is lost, revoke it and create a new one.
Use it
Send the key in the Authorization header on every request:
curl https://upscalr.app/api/v1/jobs \
-H "Authorization: Bearer $UPSCALR_API_KEY"A missing, malformed or revoked key returns 401 unauthorized. Requests are only accepted over HTTPS.
Scopes
A key is created with one or both scopes, chosen when you create it. A request needs the matching scope or it is rejected with 403 forbidden and a message naming the missing scope. The request never even reaches the part that would need it.
| Parameter | Type | Description |
|---|---|---|
| jobs:read | scope | Retrieve a job, list jobs, and download a result. |
| jobs:write | scope | Submit a new upscale and cancel an unfinished job. |
Give a key only what it needs. A service that only checks status and downloads results has no reason to hold jobs:write.
Keep it secret
- Store the key in an environment variable (
UPSCALR_API_KEYin every example in these docs) or a secrets manager, never in source control or client-side code. - Calls must come from your server. A key shipped inside a browser bundle or mobile app is public the moment you deploy.
- Use one key per environment or integration, so a leak is revocable without taking everything else down.
- Rotate by creating the new key first, deploying it, then revoking the old one. Revocation takes effect immediately.