Authentication

Every request to the API carries an API key in the Authorization header, as a bearer token. The key proves who is calling, names the project the request acts on, and carries the scopes that decide which endpoints it may call.

curl https://api.useinfrared.com/v1/usage \
  -H "Authorization: Bearer $INFRARED_KEY"

const response = await fetch("https://api.useinfrared.com/v1/usage", {
  headers: { Authorization: `Bearer ${process.env.INFRARED_KEY}` },
});

const usage = await response.json();

import os
import requests

response = requests.get(
    "https://api.useinfrared.com/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['INFRARED_KEY']}"},
)

usage = response.json()

You create and revoke keys in the dashboard, under Settings, API keys. The API has no endpoint for it, so a key can never make another key. API keys walks through creating one.

The header

Authorization: Bearer ir_live_...

• The word is Bearer, with a capital B, then a space, then the key. A lowercase bearer, another scheme, or a key in the query string counts as no key at all.
• A key is ir_live_ or ir_test_ followed by 32 letters and digits, 40 characters in all.
• Infrared stores a hash of the key, never the key. It is shown once, when you create it.

What a key can reach

A key belongs to one project. Lists, lookups and writes are all scoped to it, and no path carries a project id. A resource of another project answers 404, as if it did not exist.

A test key authenticates the same way and reaches the same project. Only the creation of a moderation treats it differently: no checks are used, usage is counted apart and author history is left alone. Every other call made with a test key changes real data.

Scopes

A key has one or more of three scopes. Each endpoint asks for exactly one, and scopes do not include one another.

Two consequences to plan for:

• Polling needs read. A key with moderate alone can start a queued moderation and cannot fetch its result with GET /v1/moderations/{id}.
• Scopes are fixed. A key's scopes cannot be changed after it is created. Create a new key and revoke the old one.

When a key is refused

{
  "error": {
    "code": "missing_api_key",
    "message": "Missing or invalid Authorization header",
    "details": [],
    "request_id": "req_63717b6414df41308492b50dba455cc4"
  }
}

A revoked key stops working at once, and an expired one at its expiry time. Neither comes back: create a new key.

A request refused with 401 does not count against the rate limit. One refused with 403 does.

Next

• API keysA key signs every request and decides which project it lands in. Create one for each place that calls Infrared, with only the scopes it needs.
• Test modeA test key runs the whole pipeline and uses no checks. It is not a sandbox: its moderations still reach the review queue and your webhooks.
• ErrorsEvery error has one JSON shape. Branch on its code, show its details and quote its request id. The table lists each code the API returns and when.
• Rate limitsEach API key may send a set number of requests a minute, by plan. Every response says where the key stands, and a 429 says how long to wait.