Docs
Guides

API authentication

How to create an Iminify API key, send it as a Bearer token, keep it safe and replace it, and which accounts can use the API.

Every request to the API carries a personal access token, which these pages call an API key. The key stands in for your account: whatever you can do on the website, the key can do, on your images and against your plan's allowance.

Creating a key

  1. Sign in and open Settings > API Tokens.
  2. Name the key after what will use it: build-server, wordpress-sync, laptop. The name is only for you.
  3. Press Create and copy the key. It's shown once; we keep only a hash of it, so nobody can show it to you again.

Make one key per script or server. When one leaks or a machine is retired, you delete that key and nothing else breaks.

Sending it

Put the key in the Authorization header as a Bearer token, on every request:

HTTP 
GET /api/v1/account HTTP/1.1
Host: www.iminify.com
Authorization: Bearer Yc2hT9vKq3mW8aLr...
Accept: application/json

The samples on these pages read the key from the IMINIFY_API_KEY environment variable, so it never ends up in your code:

Shell 
export IMINIFY_API_KEY="paste-your-key-here"

A key has no scopes and no expiry date. Keys made in the settings page are all alike, and each one can do everything your account can.

Who can use the API

Any account whose email address is verified, on any plan, within that plan's limits (the pricing page has them). There is no separate API plan. An account that hasn't followed its verification link yet is refused with 403 and email_not_verified; the same key works as soon as the link has been followed. A banned account's keys stop working with the ban.

Keeping it safe

  • Call the API from a server or a script, never from a browser or a mobile app. Anything shipped to a visitor's device can be read by them, key included.
  • Keep keys out of repositories. An environment variable or your platform's secret store is the place for them.
  • If a key leaks, delete it in Settings > API Tokens and create a new one. Deleting it takes effect on the next request.
  • The settings page shows when each key was last used, which is how you find the ones nothing uses any more.

When it goes wrong

Status Code What it means
401 unauthenticated No key, or one that doesn't exist: mistyped, cut short, or deleted.
403 email_not_verified The account hasn't verified its email address yet.
403 account_banned The account behind the key has been banned.

Every other error is on the errors page.

On this page