Authentication

Every create or management request uses an API key. Create an App to store images for your backend, then turn on sign-in when people need separate storage of their own.

Create an API key

Open Apps, create an App, then issue its first key from the App’s Keys page and save the plaintext shown once. This first key is fixed to the App’s own storage. Turn on sign-in from the App’s Users page when people should sign in to it, then create a separate key in Keys → New key with data access set to This App and its users. Turning on sign-in never expands an existing key’s scope. Keep the key on your backend, never in browser code, a mobile binary, or a public repository.

Create an App

http

Authorization: Bearer YOUR_API_KEY

Request

bash

curl -X POST "https://test.api.img.pro/v1/images" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@photo.jpg"

Without a user selector, an App key acts on the App’s own storage. This is separate from the App owner’s connected-user storage.

Key scopes and permissions

app App-wide scope: Access the App storage by default, or a connected user’s bucket with X-Img-User. Only the App owner manages these keys. App suspension stops App-wide access.
bucket fixed storage scope: Access only the bucket that owns the key. Existing fixed-bucket keys keep their scope and never gain App-wide access. They do not accept a user selector.
read: Read images, lists, usage, and billing status.
write: Upload, update, and delete images, including batch mutations.

Scopes and permissions belong to the credential; its text prefix does not choose the destination.

Access your media in a connected App

Open the App under Apps you use, then choose Manage keys to open Keys. New consumer keys are read-only and access only your media in that App, including private images. They cannot upload, edit, delete, select another user, or exchange login codes.

Existing keys keep their permissions. You may rename, revoke or reduce your own keys’ permissions, but cannot add write access. A replacement consumer key is read-only. Disconnect and delete data also revokes the keys for that connection.

App owners can create multiple named keys on the App’s Keys page. Creating a key never invalidates another; revoke the selected old key after updating its integration.

Act for a connected user

Connect the user through hosted login, exchange the one-time code on your backend, then use their returned opaque user.id:

http

Authorization: Bearer YOUR_APP_KEY
X-Img-User: m3k9ab2c

The header selects that user’s bucket within your App. It cannot address arbitrary accounts or another App’s storage. Omit it to use the App storage. A present blank or malformed value returns 422 validation_error; an unavailable or unconnected user returns 403 user_forbidden. A rejected selector never falls back to the App storage.

X-Img-Team is unsupported and returns 422. Sending X-Img-User with a fixed-bucket key also returns 422.

Building an app

Usage during the transition

App creation, uploads, storage, and transforms are free during the transition, without plan-based limits. GET /v1/usage reports actual usage and limits_enforced: false. Legacy plan limit fields remain informational. File-size, format, rate, authorization, and lifecycle checks still apply. Existing subscriptions continue until changed or canceled.