Authentication

Every API request carries a key as a bearer token:

curl https://api.h3.studio/v2/video_generation \
  -H "Authorization: Bearer h3sk-…"

Getting a key

Create one in the console, under API keys. The key is shown once, at creation. We store an argon2 hash and a short prefix — we cannot recover the key for you, and neither can anyone who steals the database.

Name your keys after where they run (production, ci, laptop). When one leaks, you want to revoke exactly one thing.

Revoking

Revocation takes effect immediately: the next request with that key gets a 401. There is no grace period, so rotate by issuing the new key first, deploying it, and revoking the old one after.

What a 401 looks like

{
  "type": "error",
  "error": {
    "type": "authorized_error",
    "message": "authentication failed, please carry the API secret key in the 'Authorization' field of the request header (1004)",
    "http_code": "401"
  },
  "request_id": "021785229015510a2c883cf675b9804d"
}

Every authentication failure returns the same message — unknown key, revoked key, expired key, suspended account. That is deliberate: a more specific error would tell someone guessing keys which guesses were close.

Keep keys server-side

A key authorises spending money. Never ship one to a browser or a mobile app: anyone who opens the network tab has it. Call this API from your backend, and give your own users your own credentials.

If you need a browser to upload media directly, use the files API — it hands out a short-lived signed URL scoped to a single object, which is exactly the thing you can safely give a browser.

The console uses a different credential

Signing in to the website creates a session cookie, which works only on /console/v1/*. API keys do not authenticate the console, and session cookies do not authenticate the API. Two audiences, two credentials, no overlap.