Authentication

Every FilesHub request is authenticated with an X-API-Key header carrying a per-project key. There are no user logins or OAuth tokens in the object API — the key identifies the project, its permissions, and its restrictions.

X-API-Key: fh_live_xxxxxxxxxxxxxxxx

Key types

Prefix	Use
fh_live_…	Production traffic.
fh_test_…	Development and testing against the same API surface.

Permissions & scopes

A key carries scopes:

• read — list objects and download objects, including private ones in the key's project; list jobs, templates, and schedules.
• write — upload and delete objects; manage templates and schedules.
• email — send email via the email API.
• email_template — manage email templates (paired with write).
• service scopes — per-utility access (e.g. converter, qr_code); all enabled by default, so most keys reach every utility unless a scope was turned off.

Give a key only what it needs. A public website that just renders already-uploaded public files needs no key at all to display them; a server that uploads needs write; a server that fetches private files needs read.

Restrictions (ship a key in a frontend)

A key can be marked restricted so it only works from your own app — a web origin, an Android package (optionally pinned to its signing certificate), or an iOS bundle id. That lets you embed the key in a React or mobile app without a proxy backend.

Android request example

X-API-Key: fh_live_xxx
X-App-Id: com.example.myapp
X-Android-Cert: AB:CD:...   # signing-cert SHA-256, when pinned

API key restrictions covers the full setup — web origins and wildcards, Android package + certificate pinning (with keytool and a Kotlin snippet), iOS bundle ids, and where restrictions stop and a real backend is still needed. Manage restrictions per key in the Nova admin panel (Projects → API Keys).

Keeping keys safe

1. A write live key belongs on a server, in an environment variable — never hardcoded in a public bundle. To use a key in a frontend, mark it restricted and scope it to your origins/app (see above), and keep its scopes minimal.
2. Store keys in environment variables, never in source control. (FilesHub's own repo keeps its secrets in a private repo for this reason.)
3. Prefer read-only keys wherever you don't upload or delete.
4. Rotate keys if one is exposed — create a new one in Nova and retire the old.

What a missing or wrong key returns

• No X-API-Key on a write/list endpoint → 401 with { "message": "API key is required..." }.
• A key without the needed permission → 403.
• A restricted key used from a disallowed origin/app → 403.

See Errors & limits for the full table.