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;
adminincludes all scopes. Insufficient scope returns403 HS_FORBIDDEN. - App context: operations with
{app_id}in the path (/v1/apps/{app_id}/…) act on that app; flat operations such as/v1/notificationsuse theapp_idquery/body field. With an app-bound key, the bound app is used even ifapp_idis omitted; with an org-wide key,app_idis required. Another app's ID returns404 HS_NOT_FOUND. - Org-wide operations (
GET /v1/apps,POST /v1/apps,GET /v1/organization*) require an org-wideadminkey. - API keys are valid only on
/v1routes;/internaland/adminrequire 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 returns401 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) | Proof | How to produce it |
|---|---|---|
hmac | identity_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 |
jwt | ES256 JWT: sub = external_id, aud = app_id, exp; verified with the public key (kid) registered to the app | Register the public key with POST /v1/apps/{app_id}/identity-keys; identityToken(...) helper in the server SDKs (JWT guide) |
both | Either one | For 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
| Status | Code | Meaning |
|---|---|---|
| 401 | HS_UNAUTHENTICATED | Missing header, wrong format, key revoked/expired |
| 403 | HS_FORBIDDEN | Insufficient scope, IP allowlist, failed proof of ownership/identity verification, org-wide operation with an app key |
| 403 | HS_ORG_SUSPENDED | Organization suspended |
| 403 | HS_SSO_REQUIRED | (Dashboard) SSO-only org |
| 404 | HS_NOT_FOUND | Resource doesn't exist or belongs to another tenant |
| 421 | HS_WRONG_CELL | The request belongs to an org in another data region; use the correct root from details.api_url |
API overview
Pushizo public REST API — base URL, authentication and scopes, request/response conventions, error envelope, rate limits, pagination, idempotency, webhook signatures, versioning, data residency, SDKs, MCP, OpenAPI and Postman.
Rate limits and quotas
Plan-based API request rate (api_rps), X-RateLimit headers, 429 and Retry-After behavior, per-endpoint limits, nginx IP limits, plan quotas and SDK retry rules.