Hakari

API keys

API keys let you call every project-scoped endpoint Hakari exposes without holding a user session. They're project-scoped — one key can act on exactly one project.

Create

Dashboard → API Keys → Create API key:

  • Label — free-form. Use it to distinguish Production backend from Staging CI.
  • Scopes — what this key can do (see Scopes).

You'll see the raw key once, prefixed hkr_. Copy it into your secrets manager immediately — we store only a SHA-256 hash and can't resurface it later.

hkr_xR8wN4pQmKvL3yT7cZdBfU2hJsA9eD1nGqYtH6XVcW-4

Using the key

Send it as a Bearer token:

curl https://api.hakari.cloud/v1/projects/my-project/streams \
  -H "Authorization: Bearer hkr_xR8wN4pQmKvL3yT7cZdBfU2hJsA9eD1nGqYtH6XVcW-4"

No other auth needed — this replaces session cookies entirely.

Scopes

Each key holds one or more scopes. Endpoints that are scope-protected enforce one-of the listed scopes.

| Scope | Grants | | --- | --- | | streams:read | List, get, playback tickets. | | streams:write | Everything in streams:read + create, update, rotate, disable. | | vod:read | List VODs, get, playback tickets. | | vod:write | Everything in vod:read + create (upload), cancel, toggle signed playback. | | * | Wildcard — every scope, including ones added in the future. |

Default on create is *. For a production integration that only streams video, a minimal key might be streams:write + vod:write; for a read-only dashboard, streams:read + vod:read.

Security

  • Stored hashed. We keep sha256(key) and a 12-char prefix for identification. Even a database dump doesn't let an attacker reconstruct raw keys.
  • Revocable instantly. Click Revoke — the key stops working on the next request. Revocation is sticky (no re-enable); mint a fresh key if you need one back.
  • lastUsedAt — sampled per key so you can see which keys are actually in use and prune the dormant ones.

Best practices

  • One key per environment. Prod / staging / CI / local dev. Makes rotation and blast-radius reasoning easier.
  • Don't ship keys to browsers. A key is equivalent to the project's admin session. Keep it server-side.
  • Rotate on offboarding. If the person who held the secret leaves, revoke the key. There's no shared-user model; revoke + issue is the audit trail.
  • Prefer narrow scopes. streams:read on a public-facing status page key is safer than *.

Compared to session auth

| | API key | User session | | --- | --- | --- | | Credential lifetime | Until revoked | Short JWT (minutes) | | Scope enforcement | Per-endpoint @ApiScopes | Role-based (viewer / member / admin) | | Who can mint | Project admin | Invited users sign in | | Where it lives | Server-side secret | Browser cookie |

Internally the GlobalGuard detects Bearer hkr_… and swaps the session path for key-based auth. Same endpoints, same JSON shapes.