PushizoDocs
API reference

Authentication

Bearer API keys, scopes and app/org context for the public API; proof of ownership (token_hash) and identity verification (identity_hash HMAC or ES256 JWT) on client SDK endpoints; error responses.

Public API (/v1)

GET /v1/apps/app_01J…/users?limit=50 HTTP/1.1
Host: api.pushizo.com
Authorization: Bearer hs_live_…
  • Create a key on the Organization → API keys screen or with POST /v1/apps/{app_id}/api-keys; the raw value is shown only in the creation and rotation response (API keys).
  • Scope: the scope each operation requires is listed under the operation title in the reference; admin includes all scopes. Insufficient scope returns 403 HS_FORBIDDEN.
  • App context: operations with {app_id} in the path (/v1/apps/{app_id}/…) act on that app; flat operations such as /v1/notifications use the app_id query/body field. With an app-bound key, the bound app is used even if app_id is omitted; with an org-wide key, app_id is required. Another app's ID returns 404 HS_NOT_FOUND.
  • Org-wide operations (GET /v1/apps, POST /v1/apps, GET /v1/organization*) require an org-wide admin key.
  • API keys are valid only on /v1 routes; /internal and /admin require a session cookie (dashboard).
  • If an IP allowlist is defined, requests from outside it get 403 (details.reason: ip_not_allowed); an expired/revoked key returns 401 HS_UNAUTHENTICATED.

In the server SDKs, the key is passed in the configuration (new Pushizo({ apiKey }), Pushizo(api_key=…), pushizo.NewClient(key)…).

Client SDK endpoints (/sdk/v1)

Client SDKs (browser, mobile) carry no API key; they work with the App ID only. Security is provided by two mechanisms:

Proof of ownership (token_hash)

When a subscription is created, the device token (APNs/FCM/HMS token, Web Push endpoint, email, phone) is recorded. Subsequent requests (PATCH /sdk/v1/apps/{app_id}/subscriptions/{id}, login, logout, events, delivery feedback, in-app/inbox, preferences) prove ownership of the subscription with token_hash = SHA-256(token); a non-matching request gets 403. This way, a third party who knows a subscription ID cannot modify it.

Identity verification

If Identity verification is enabled in the app settings, login(external_id) and user updates are accepted only with a proof signed by your server:

Mode (identity_verification_mode)ProofHow to produce it
hmacidentity_hash = HMAC-SHA256(sdk_secret, external_id) (hex)Server SDKs: Pushizo.identityHash(sdkSecret, externalId) (Node), Client::identityHash (PHP), etc. sdk_secret is on the App settings → SDK screen
jwtES256 JWT: sub = external_id, aud = app_id, exp; verified with the public key (kid) registered to the appRegister the public key with POST /v1/apps/{app_id}/identity-keys; identityToken(...) helper in the server SDKs (JWT guide)
bothEither oneFor a transition period

The SDKs take the proof via login(externalId, identityHash) or login(externalId, { jwt }) and attach it to subsequent requests for that user. A login without a proof returns 403 HS_FORBIDDEN; anonymous usage is unaffected.

Privacy consent

While requiresPrivacyConsent is on, the SDK sends no requests until setConsentGiven(true) is called; there is no additional flag on the server side.

Dashboard and platform (/internal, /admin)

Session cookie (hs_session, HttpOnly; Secure; SameSite=Lax) + x-csrf-token; Origin check on mutations. These endpoints are not part of the public contract; a separate openapi-internal.yaml is generated for the type-safe client. Platform admin endpoints additionally require MFA.

Error responses

StatusCodeMeaning
401HS_UNAUTHENTICATEDMissing header, wrong format, key revoked/expired
403HS_FORBIDDENInsufficient scope, IP allowlist, failed proof of ownership/identity verification, org-wide operation with an app key
403HS_ORG_SUSPENDEDOrganization suspended
403HS_SSO_REQUIRED(Dashboard) SSO-only org
404HS_NOT_FOUNDResource doesn't exist or belongs to another tenant
421HS_WRONG_CELLThe request belongs to an org in another data region; use the correct root from details.api_url

On this page