Authentication
API keys, publishable keys, and dashboard session cookies.
0fra has two authentication channels and you'll use both:
| Channel | When to use |
|---|---|
| Bearer secret key | Server-to-server calls from your backend |
| Session cookie | Dashboard SPA at dash.0fra.dev (signed-in user) |
| Publishable key | Front-end identification only — no privileged actions |
Secret key (sk_live_…)
Issued once during platform onboarding. Stored as SHA-256 hash on our side; if you lose it, rotate it (you can't recover).
GET /v1/orders HTTP/1.1
Host: api.0fra.dev
Authorization: Bearer sk_live_2f037751f1b3f7e2130fb2d666a7dcfe9678af801f42d740- Treat it like a database password. Never embed it in client code, mobile apps, or git.
- Use environment variables (
SPLITFI_SECRET_KEY) and a secrets manager in production.
Publishable key (pk_live_…)
Safe to put in front-end code — it identifies your platform when initiating Hosted Checkout from a static page or SDK. It cannot list orders, refund, or rotate keys.
Today the publishable key is just an identifier; future SDKs will require it to bootstrap browser-side flows.
Session cookie
The 0fra Dashboard signs users in via better-auth (email + password for MVP, with OAuth on the roadmap). Once signed in, the browser holds a splitfi.session_token cookie. The same /v1 endpoints accept this cookie as authentication, so the dashboard never has to know your secret key.
If you build your own internal admin tools, you can hit /api/auth/sign-in/email and reuse the cookie the same way.
Idempotency
Every state-changing request must carry an Idempotency-Key header. We store the hash of the request body and the response, so retrying the same key returns the cached response.
- Use a fresh UUID per logical operation
- Reusing a key with a different body returns
409 duplicate_idempotency_key - Cache lifetime: 24 hours
curl -X POST https://api.0fra.dev/v1/orders \
-H "Authorization: Bearer sk_live_..." \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d @order.jsonRotating keys
From the Dashboard's Developers tab you can:
- View all your keys (only the prefix is shown — full value is gone)
- Create a new key
- Revoke a key (status flips to
revoked)
There's no rate-limit yet on rotation, but each rotation invalidates the old key immediately — coordinate with your servers.
CORS
/v1/* routes return CORS headers that allow any browser origin to call them with bearer tokens. Cookie-based requests are limited to trusted origins configured at the 0fra level (today: dashboard URLs only — contact us to allowlist additional origins).