Start here

Authentication

Every /v1 request uses a bearer API key. Keys belong to one HoneyNotify app, so a valid key can never access another app's devices, users, notifications, or analytics.

Key types#

Server keys#

Server keys begin with ps_live_. They are confidential credentials intended for backend applications, trusted jobs, and reporting services. You select their scopes when creating them.

Public client keys#

Public client keys begin with ps_public_. They are designed to be embedded in iOS, Android, and browser clients. The server restricts them to:

POST /v1/devices/register;
DELETE /v1/devices/{device_id}; and
POST /v1/events.

Even if a public key is configured incorrectly, HoneyNotify will not allow it to list audiences, read analytics, or send notifications.

A public client key limits capability; it does not prove who the end user is. Enable identity verification when clients associate devices with user accounts.

Sending the key#

Use the HTTP Authorization header on every request.

curl https://api.honeynotify.com/v1/devices \
  --header "Authorization: Bearer $HONEYNOTIFY_API_KEY"

Do not place keys in query strings. URLs can be stored in browser history, reverse-proxy logs, and analytics systems.

Scopes#

Scope	Permits
`devices:write`	Register, inspect, disable, and manage devices, users, and aliases.
`notifications:write`	Create/cancel notifications and manage segments, templates, webhooks, journeys, exports, and app delivery settings.
`notifications:read`	Read notifications, recipients, events, segments, templates, webhooks, journeys, analytics, and exports.
`events:write`	Submit lifecycle, custom, and outcome events.
`*`	All server-key operations; reserve this for tightly controlled administration.

Device and user GET routes require devices:write, not notifications:read. Create separate keys if a service should only report notification data.

Key rotation#

Rotate without downtime:

Create a replacement key with the same minimum scopes.
Add it to your secret manager and deploy it to all callers.
Confirm the new key's last used value in the dashboard.
Revoke the old key.
Investigate any calls that continue using the revoked credential.

Never log a complete key. If you suspect exposure, revoke it immediately; hashing at rest cannot protect a key that has leaked from a client or log.

Verified user identity#

Without verification, a client can submit any external_user_id. Identity verification makes HoneyNotify accept that association only when accompanied by a short-lived ES256 JWT issued by your backend.

Configure your ES256 public key in app settings, then enable identity_verification_required. For each logged-in user, your backend signs a token with:

iss: the HoneyNotify app public ID;
sub: your external user ID, or the same value in identity.external_user_id; and
exp: an expiry no more than one hour in the future.

The client supplies the token as identity_token when registering or identifying. If it also supplies external_user_id, the two values must match.

Anonymous registration remains possible when no user association is supplied. Once verification is required, never generate the identity token in the client—the private signing key belongs only on your backend.

Authentication failures#

{
  "error": {
    "code": "insufficient_scope",
    "message": "Insufficient scope",
    "details": {}
  },
  "request_id": "c1a26486-1da3-4fcc-9273-623ad0d52f68"
}

401 means the credential could not be authenticated. 403 means it was authenticated but cannot perform that operation. Do not repeatedly retry either response without changing the key or its scopes.