PushizoDocs
Security & compliance

API keys and scopes

Public API keys — format, app/org scope, the list of scopes and the role rule, IP allowlist, expiry date, rotation, revocation and best practices.

An API key (hs_live_ or hs_test_ prefix + 40 base62 characters) is for server-side access and is sent in the Authorization: Bearer header. The key is stored as a SHA-256 digest; the raw value is only shown in the creation and rotation responses. Manage keys in the dashboard under Organization → API keys or with POST /v1/apps/{app_id}/api-keys (admin).

Scope list

ScopeGrantsRequired member permission
notifications:writeCreate/cancel notifications, estimate recipients, trigger journey runscampaigns.send
users:readRead users, subscriptions, aliases, notification inbox, preferences, suppressionsusers.read
users:writeWrite users/subscriptions/aliases/preferences/suppressions, KVKK deletionusers.write
events:writeSend eventsusers.write
segments:readList, preview and estimate segmentsusers.read
analytics:readReports; message/campaign/journey/template/in-app statistics and listsanalytics.read
mcp:writeMCP write tools: only create campaign/segment drafts, never sendcampaigns.create, segments.write
adminAll scopes + channel credentials, webhooks, template/campaign/journey/in-app management, export/import, API keys, app creation, org/audit readsall permissions (owner/admin only)

Rule: the role of the member creating/editing/rotating the key must have all the permissions required by the granted scopes (privilege escalation prevention). The scope each operation requires is listed under the operation heading in the API reference.

App and org scope

  • App-bound key: only that app's resources; the bound app is used even if app_id is not given in the path/query/body.
  • Org-wide key (app_id: null): all apps; required for GET /v1/apps, POST /v1/apps, GET /v1/organization* and usage. Members restricted to specific apps with app_scopes cannot create org-wide keys.

Fields

FieldDescription
nameDisplay name
scopes[]At least one scope
environmentlive (default, prefix hs_live_) or test (prefix hs_test_); used to separate production/staging integrations
ip_allowlist[]CIDR (IPv4/IPv6); unrestricted if empty. Requests from outside return 403 HS_FORBIDDEN (details.reason: ip_not_allowed). Behind a proxy, the real IP is taken with TRUST_PROXY
expires_atExpiry; after it passes, 401 HS_UNAUTHENTICATED

Lifecycle

ActionEndpoint
CreatePOST /v1/apps/{app_id}/api-keys → { id, key, prefix, scopes, … } (the raw key is only returned here)
ListGET /v1/apps/{app_id}/api-keys (prefix, scopes, last used, expiry)
UpdatePATCH …/api-keys/{key_id} (name, scopes, IP list, expiry)
RotatePOST …/api-keys/{key_id}/rotate → new raw key; the old key is invalidated immediately
RevokeDELETE …/api-keys/{key_id}; the revocation cache clears within ≤ 5 s

Examples: API → API keys. Creation, updates, rotation and revocation are written to the audit log (name, prefix, scopes, IP list).

Error responses

StatusCodeReason
401HS_UNAUTHENTICATEDMissing/invalid header, revoked or expired key, request to an /internal route with an API key
403HS_FORBIDDENInsufficient scope, outside the IP allowlist, an org-wide operation attempted with an app key
403HS_ORG_SUSPENDEDOrganization suspended (only billing can be read)
429HS_RATE_LIMITED / HS_QUOTA_EXCEEDEDRate limit or plan quota

Best practices

  • Use a separate key with the narrowest scopes for each integration; use admin only for management automation.
  • Keep keys in environment variables; never put them in client code, mobile apps or your repository. The dashboard Logs screen shows when a key was last used.
  • Separate live/test environments for production/staging; rotate on suspicion of a leak (the old key is invalidated instantly, so update your application with the new key at the same time).
  • If you are behind a proxy/NAT, restrict the IP allowlist to your egress IPs.
  • In the SDKs, baseUrl/apiUrl must be HTTPS; redirects to the regional API root (421) are followed by the SDK (data residency).

On this page