Authentication · API docs

Create an API key

Open Apps, create an App, then issue its first key from the App’s API Keys page and save the plaintext shown once. Its reach is App storage only: it works in the App’s own images. Turn on sign-in from the App’s Connect page when users should sign in to it, then create a separate key in API Keys → New key with data access set to App-wide. Turning on sign-in never widens an existing key’s reach. 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://api.img.pro/v1/images" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@photo.jpg"

Without a user selector, an App-wide key acts on the App’s own storage. If you also sign in to your own App, your storage there is separate from the App’s.

Key reach and permissions

app App-wide: Works in the App storage by default, or in a connected user’s storage with X-Img-User, and finishes sign-ins when it has read. The App’s owner and its admins create and revoke these keys, and only a key’s creator changes it. A key stops working when its creator is no longer an admin. While the App is paused or blocked, App-wide keys are refused.
bucket App storage only: Works only in the storage the key was created in: the App storage, or a connected user’s own key in their storage. It never gains App-wide reach and does not accept a user selector.
read: Read images, lists, usage, and billing status.
write: Upload, update, and delete images, including batch mutations.

Reach and permissions belong to the key; its text prefix does not choose the destination. The API Keys list shows the last four characters of newer keys, so you can match a row to the key in your environment.

The App’s owner and its admins can create multiple named keys on the App’s API 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 img.pro sign-in, exchange the one-time code on your backend, then use their returned opaque user.id:

http

Authorization: Bearer YOUR_APP_WIDE_KEY
X-Img-User: m3k9ab2c

The header selects that user’s storage 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.

Sending X-Img-User with a key that is not App-wide returns 422.

Build an App

Usage and limits

Free: up to 5,000 images and 50 users per App. Pro: up to 50,000 images and 500 users per App, $20 a month. Unlimited: no limits, $100 a month.

The limits count the whole App: the images in its own storage and in every connected user’s, and its users. On Free, once the App holds 5,000 images a new upload or URL import returns 403 quota_exceeded and stores nothing, and once 50 users are connected a new user’s first sign-in through img.pro is refused. Pro does the same at 50,000 images and 500 users, and Unlimited has no limits. Everything already stored keeps serving, and everyone already connected keeps signing in. Upgrade the App in Billing: Free to Pro, Pro to Unlimited.

GET /v1/usage reports the App’s plan and both counts against their limits, with limits_enforced: true on Free and Pro and false on Unlimited. Its monthly upload and storage limit values (uploads_limit, storage_limit_bytes) are informational and never refuse an upload. File-size, format and permission checks apply on every plan alike.

Your own keys in an App you use

Open your connection to the App under Apps you use: its API access card lists your keys and creates new ones. A new key is read-only and reaches only your images in that App. It cannot upload, edit, delete, select another user, or finish sign-ins.

Existing keys keep their permissions. You may rename or revoke your own keys; their permissions are fixed, so you cannot add write access, and a replacement key is read-only. Disconnect and delete data also revokes the keys for that connection. While the App is paused you can’t create keys, and you can still rename and revoke the keys you have.