User tokens

Why user tokens

Hive Push lets you send to your own user ids and shows each user their own inbox. To do that safely, a browser can only claim to be a user with a user token that your server makes with the app’s secret key. Nobody can subscribe as someone else, receive their notifications or read their inbox, even with your public key.

Make a fresh token each time a signed-in user loads your site, and pass it to the SDK:

await push.setUser(userId, token);

Format

user_token = base64url(JSON {"u": "<user id>", "exp": <unix seconds>})
             + "." + hex(HMAC-SHA256(secret_key, <that first part>))

• u is your user id: any string up to 200 characters.
• exp is when it expires, in Unix seconds. Tokens can live at most 30 days; one hour is a good lifetime.

A missing, malformed, expired or wrongly signed token is refused with 401 invalid_user_token. Rotating the secret key in the console makes every token signed with the old key invalid.

Make one on your server

Node.js

import crypto from 'node:crypto';

function hivePushUserToken(secretKey, userId, ttlSeconds = 3600) {
  const body = Buffer.from(JSON.stringify({ u: userId, exp: Math.floor(Date.now() / 1000) + ttlSeconds })).toString('base64url');
  return body + '.' + crypto.createHmac('sha256', secretKey).update(body).digest('hex');
}

Python

import base64, hashlib, hmac, json, time

def hive_push_user_token(secret_key, user_id, ttl=3600):
    body = base64.urlsafe_b64encode(json.dumps({"u": user_id, "exp": int(time.time()) + ttl}).encode()).rstrip(b"=").decode()
    return body + "." + hmac.new(secret_key.encode(), body.encode(), hashlib.sha256).hexdigest()

Only hand a token to the user it’s for: return it from an endpoint that checks your own session.

Or ask the API

If you’d rather not sign tokens yourself, ask for one with the secret key:

curl https://push-global-1.dockhive.io/v1/apps/app_0123456789abcdef/user-tokens \
  -H "Authorization: Bearer $HIVE_PUSH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user-42", "ttl": 3600}'

{"user_token": "eyJ1Ijoi...", "expires_at": "2026-11-12T10:00:00Z"}

ttl is in seconds, 60 to 2592000 (30 days); the default is 86400 (one day).

Logout

When the user signs out, detach them from the browser:

await push.setUser(null);

The browser keeps its push subscription, but no longer belongs to the user: it stops getting notifications sent to that user and can’t read their inbox. To stop notifications in this browser altogether, call push.unsubscribe().

Delete a user’s data

When a user deletes their account, or asks you to remove their data:

curl -X DELETE https://push-global-1.dockhive.io/v1/apps/app_0123456789abcdef/users/user-42 \
  -H "Authorization: Bearer $HIVE_PUSH_SECRET_KEY"

Answers 204. It removes the user’s devices and inbox and closes their live inbox connections. URL-encode the user id.