Identity verification with JWT (SDK identity verification)
When you pass your user identity (external_id) to the SDK, proof is required to prevent impersonation of another user. There are two methods, selected in the app settings (ADR-0023 §9):
When you pass your user identity (external_id) to the SDK, proof is required to prevent impersonation of another user. There are two methods, selected in the app settings (docs/adr/0023-kurumsal-kimlik-sso-scim-jwt.md §9):
| Mode | Proof |
|---|---|
hmac (default) | identity_hash = HMAC-SHA256(sdk_secret, external_id) — does not expire |
jwt | A JWT signed with ES256 on your server, valid for at most 24 hours |
both | Either one (transition period) |
Select the mode and add your public key under Settings → App → JWT identity verification. If "Identity verification required" is on, requests without proof of the selected type get a 403.
1. Generate a key pair
openssl ecparam -name prime256v1 -genkey -noout -out hs-identity.pemopenssl ec -in hs-identity.pem -pubout -out hs-identity.pub.pemAdd the contents of hs-identity.pub.pem in the dashboard (or via POST /v1/apps/{appId}/identity-keys); you will be given a kid. The private key stays only on your server; it is never sent to Pushizo (requests containing a private key are rejected).
2. Generate the token on your server
Claims: sub = external_id, aud = app ID, iat, exp (at most 24 hours); in the header, alg: ES256 and kid.
import { Pushizo } from '@pushizo/node';
const jwt = Pushizo.identityToken({ privateKey: process.env.HS_IDENTITY_KEY!, kid: 'main', appId: 'app_…', externalId: user.id, expiresInSeconds: 3600 });$jwt = \Pushizo\Client::identityToken(getenv('HS_IDENTITY_KEY'), 'main', 'app_…', $user->id, 3600);from pushizo import identity_token # pip install "pushizo[jwt]"
jwt = identity_token(os.environ["HS_IDENTITY_KEY"], "main", "app_…", user.id, expires_in=3600)jwt, err := pushizo.IdentityToken(pushizo.IdentityTokenOptions{PrivateKeyPEM: key, Kid: "main", AppID: "app_…", ExternalID: user.ID, TTL: time.Hour})String jwt = com.pushizo.IdentityToken.create(pem, "main", "app_…", user.getId(), Duration.ofHours(1));var jwt = Pushizo.IdentityToken.Create(pem, "main", "app_…", user.Id, TimeSpan.FromHours(1));jwt = Pushizo.identity_token(pem, kid: "main", app_id: "app_…", external_id: user.id, expires_in: 3600)3. Pass it to the SDK
Your app fetches the token from your own authenticated API and passes it to the SDK at login. The SDK carries the token in the Authorization: Bearer header on all SDK requests (it is never written to the URL or the body).
await Pushizo.login(user.id, { jwt });
// Refresh it before it expires:
await Pushizo.updateUserJwt(newJwt);The mobile SDKs and bridges offer the same API (login(externalId, jwt), updateUserJwt(jwt)); details are in each SDK's documentation. On logout (logout), the token is deleted.
Key rotation
Add the new key (with a different kid), update your server to sign with the new key, and once old tokens have expired (at most 24 hours), disable the old key with Revoke. Tokens signed with a revoked key are rejected immediately. An app can have at most 10 active keys; when there are multiple keys, the kid in the header is required.
Suppression list
The email and SMS send-block list — reasons (bounce, complaint, STOP, manual, one-click), masked storage, API and dashboard management, the include_unsubscribed exception.
User data and KVKK/GDPR
Privacy tools for end-user data — consent (requiresPrivacyConsent), data export and deletion endpoints, retention periods, anonymization, webhook and backup implications.