Your server calls the API with a project API key. Browsers never hold a key: they receive short-lived upload tokens from your server. People manage projects and keys in the dashboard with their own sign-in. Public delivery URLs need no credential at all; protected ones carry a signature instead.
A key looks like i2s_live_ followed by 36 hex characters and belongs to exactly one project. Send it as X-Api-Key or as Authorization: Bearer. Keys are created in the dashboard and the full value is shown once. Keep it in a server-side environment variable; never ship it to a browser or a mobile app.
A key only reaches its own project. A request for another project's path, file or upload answers 404, not 403, so keys cannot probe for other projects.
Calling the API with a key
# Either header works; send it on every request.
curl https://api.img2.site/v1/key \
-H "X-Api-Key: $IMG2SITE_API_KEY"
curl https://api.img2.site/v1/projects/my-store/files \
-H "Authorization: Bearer $IMG2SITE_API_KEY"
# GET /v1/key answers with the key's own project and scopes:
{
"key_id": "key_…",
"prefix": "i2s_live_3fa",
"scopes": ["files:read", "files:write"],
"project_id": "proj_…",
"project_slug": "my-store",
"organization_id": "org_…"
}| Scope | Allows |
|---|---|
files:read | Read the project, its files, upload sessions, watermark presets and usage. |
files:write | Create and complete uploads, delete files, save and delete watermark presets. |
urls:sign | Mint signed delivery URLs (POST /v1/projects/{slug}/signed-url). |
recipes:read | Read recipes. |
recipes:write | Save and delete recipes. |
A key created with no scopes (scopes: []) has all of them. A call outside the key's scopes answers 403 forbidden. The REST reference lists the scope each operation needs.
The upload router in @img2site/sdk-server creates the upload session with your key and hands the browser the session plus an upload token. The token lets the browser finish that one upload and nothing else; it expires with the session and stops working when the key is rotated. See the quickstart.
Project settings, API keys, signing keys, billing, the audit log and your organization are managed with a dashboard session only. An API key on one of those routes answers 403 browser_session_required.
401 unauthorized. Keys of a suspended project stop authenticating.429 rate_limited with Retry-After. A request whose credential verifies is never refused by this limit.429 rate_limited with Retry-After.