PushizoDocs
Users & segments

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):

ModeProof
hmac (default)identity_hash = HMAC-SHA256(sdk_secret, external_id) — does not expire
jwtA JWT signed with ES256 on your server, valid for at most 24 hours
bothEither 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.pem
openssl ec -in hs-identity.pem -pubout -out hs-identity.pub.pem

Add 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.

On this page