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
| Scope | Grants | Required member permission |
|---|---|---|
notifications:write | Create/cancel notifications, estimate recipients, trigger journey runs | campaigns.send |
users:read | Read users, subscriptions, aliases, notification inbox, preferences, suppressions | users.read |
users:write | Write users/subscriptions/aliases/preferences/suppressions, KVKK deletion | users.write |
events:write | Send events | users.write |
segments:read | List, preview and estimate segments | users.read |
analytics:read | Reports; message/campaign/journey/template/in-app statistics and lists | analytics.read |
mcp:write | MCP write tools: only create campaign/segment drafts, never send | campaigns.create, segments.write |
admin | All scopes + channel credentials, webhooks, template/campaign/journey/in-app management, export/import, API keys, app creation, org/audit reads | all 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_idis not given in the path/query/body. - Org-wide key (
app_id: null): all apps; required forGET /v1/apps,POST /v1/apps,GET /v1/organization*andusage. Members restricted to specific apps withapp_scopescannot create org-wide keys.
Fields
| Field | Description |
|---|---|
name | Display name |
scopes[] | At least one scope |
environment | live (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_at | Expiry; after it passes, 401 HS_UNAUTHENTICATED |
Lifecycle
| Action | Endpoint |
|---|---|
| Create | POST /v1/apps/{app_id}/api-keys → { id, key, prefix, scopes, … } (the raw key is only returned here) |
| List | GET /v1/apps/{app_id}/api-keys (prefix, scopes, last used, expiry) |
| Update | PATCH …/api-keys/{key_id} (name, scopes, IP list, expiry) |
| Rotate | POST …/api-keys/{key_id}/rotate → new raw key; the old key is invalidated immediately |
| Revoke | DELETE …/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
| Status | Code | Reason |
|---|---|---|
| 401 | HS_UNAUTHENTICATED | Missing/invalid header, revoked or expired key, request to an /internal route with an API key |
| 403 | HS_FORBIDDEN | Insufficient scope, outside the IP allowlist, an org-wide operation attempted with an app key |
| 403 | HS_ORG_SUSPENDED | Organization suspended (only billing can be read) |
| 429 | HS_RATE_LIMITED / HS_QUOTA_EXCEEDED | Rate limit or plan quota |
Best practices
- Use a separate key with the narrowest scopes for each integration; use
adminonly 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/testenvironments 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/apiUrlmust be HTTPS; redirects to the regional API root (421) are followed by the SDK (data residency).
Security overview
The Pushizo security model — authentication, RBAC, tenant isolation (RLS), secret encryption, application security (SSRF, CSP, signatures), observability and audit logging; ASVS checklist.
KVKK and GDPR compliance
Roles (data controller/processor), account owner rights (data download, account deletion, marketing consent), end-user rights, sign-up consent and terms version, retention, subprocessors, DPA and data residency.