Authentication

Three auth schemes, three audiences. Pick the one that matches the integration you're building.

Choosing a scheme

Scheme	API	Use when
`X-Hapana-API-Key`	Business	Server-to-server integrations owned by your team
OAuth 2.0 Bearer	Business	Third-party apps acting on behalf of a Hapana brand
Firebase ID token	Member (Beta)	Mobile apps, kiosks, and embed widgets acting on behalf of a member

API keys

Issued from the Hapana admin app (Settings → API). Keys are scoped to a single corporate and one of four tiers — see Rate limits for what each tier unlocks.

curl https://api.hapana-app.com/v2/clients \
  -H "X-Hapana-API-Key: hap_live_..."

Treat keys like passwords. Never embed an API key in a mobile app, web frontend, or public repository. Use OAuth or Firebase for client-side integrations.

OAuth 2.0

Standard authorization code flow with PKCE. Register your app at developers@hapana.com to receive a client ID and the consent URL pattern. Tokens are scoped to the granting brand and inherit the same rate-limit tier as the brand's primary API key.

Token lifetime

Access token: 1 hour
Refresh token: 90 days, single-use, rotated on every refresh

Firebase ID tokens (Member API)

Members authenticate with Firebase Authentication on the client (email/password, Google, Apple Sign-In). Pass the resulting ID token in the Authorization header along with the site identifier:

Authorization: Bearer <firebase-id-token>
X-Site-ID: <site-id>

Firebase rotates the ID token on the client every hour — your SDK should call getIdToken(true) when it expires. There are no login or logout endpoints on the Member API; both are handled by the Firebase SDK directly.

Rotating credentials

Rotate API keys at least every 90 days, or immediately on suspected compromise. The admin app supports overlapping keys so you can roll without downtime: issue a new key, deploy it to all callers, then revoke the old one.