Authentication

The public API uses opaque API keys you generate yourself in the FileForge web app. Keys carry your account's tier, your daily quota, and any per-key scopes you choose — they are not bearer tokens that expire.

Key format

ff_live_<32 base32 chars>

ff_live_ is the production prefix. ff_test_ is reserved for V2 sandbox keys and not minted in the v1.0.0 beta. The first 12 characters of a key are stored as key_prefix and shown in the FileForge UI for identification — the remaining bytes are hashed with SHA-256 and never stored in plaintext.

The raw key is shown to you exactly once, at creation time. If you lose it, rotate the key (revoke + re-issue) — there's no way to recover the original.

Creating a key

1. Open the web app at https://fileforge.aldrickb.app.
2. Make sure your account is on Forge Pro. If it's not, upgrade here — manual upgrades during the v1.0.0 beta, payments arrive in V2.
3. Go to Settings → API Keys.
4. Click New key. Pick a recognisable name and the scopes the key needs. The default is convert:write + files:read, which is enough for the standard upload-convert-download loop.
5. Copy the key from the reveal dialog. It is the only time it's shown.

Sending the key

Either header is accepted; pick whichever is more natural for your client:

# Authorization header (preferred)
curl -H "Authorization: Bearer ff_live_…" \
     https://fileforge-api.aldrickb.app/v1/formats

# X-API-Key header
curl -H "X-API-Key: ff_live_…" \
     https://fileforge-api.aldrickb.app/v1/formats

If both are sent, Authorization: Bearer wins.

Scopes

Pick the smallest set of scopes the integration needs. A key without a required scope returns 403 forbidden.

Scope	Grants
convert:write	Create conversions (single + bulk).
files:read	List your files, fetch presigned downloads.
files:write	Presign uploads + finalize.
files:delete	Delete files (object + DB row).

Reading conversion status (GET /v1/conversions/{id}) doesn't require any scope beyond a valid key — the per-key tier and rate-limit checks still apply.

Rotation and revocation

• Rotate in Settings → API Keys. The old key is revoked immediately and a new key with the same name + scopes is issued. The new raw key is shown once.
• Revoke in the same place. Any in-flight request authenticating with the revoked key starts returning 401 invalid API key on its very next call — the api-key middleware looks up revoked_at on every request, so there's no propagation delay.

What if my account is downgraded?

api-key-auth re-reads the owner profile on every request. If you drop back to free, every API call returns 403 API access requires Forge Pro even if the key isn't deleted. Re-upgrading restores access without needing to reissue keys (assuming you didn't revoke them).

Treat keys like passwords

• Don't commit them to git. Use .env files or a secret manager.
• Don't ship them in front-end bundles — CORS is disabled on /v1/* precisely to make this awkward, but a determined developer can still proxy the calls. Don't.
• Force-revoke any key you suspect has leaked. Rotation is fast.