Connect a browser

Attach a browser's push subscription to a recipient with a connect link.

POST/v1/connect/{token}

Auth None. The connect token in the path is the credential.

Push's connect page calls this after the person clicks Enable notifications and the browser grants permission. You do not need to call it yourself; send a connect link instead.

Request#

Path parameters#

token

stringrequired

The token at the end of the connect link.

Rules: cl_ followed by 32 letters and digits

Body#

The object PushSubscription.toJSON() returns, under subscription. Extra fields such as expirationTime are ignored. The subscription must be created with the project's vapidPublicKey from Read a connect link as applicationServerKey.

subscription.endpoint

stringrequired

The browser's push address. Accepted hosts: fcm.googleapis.com, updates.push.services.mozilla.com, web.push.apple.com, *.push.apple.com, *.notify.windows.com. No port and no credentials in the URL.

Rules: At most 2,048 characters; https on a supported push service

subscription.keys.p256dh

stringrequired

The browser's P-256 public key used to encrypt each message.

Rules: base64url, 87 characters starting with B

subscription.keys.auth

stringrequired

The browser's 16-byte authentication secret.

Rules: base64url, 22 characters

Response#

200 OK. Every field is always present.

browserId

stringrequired

The connected browser's id.

Rules: UUID

recipientId

stringrequired

The recipient the browser joined.

Rules: UUID

eventToken

stringrequired

A signed token that only works for this browser. The service worker keeps it to report events and to disconnect.

Each successful call uses one use of the link. A call that fails does not.
Connecting the same browser to the same recipient again refreshes its keys instead of adding a second browser. A browser that was disconnected is connected again.
A new browser needs room: at most 20 connected browsers per recipient and 100 per account.

Errors#

Code	HTTP	When
VALIDATION_ERROR	400	The body is not valid JSON or is over 16,384 bytes.
FORBIDDEN	403	The recipient already has 20 connected browsers, or the account has 100.
NOT_FOUND	404	The token is malformed or unknown, the link expired, was revoked or is used up, or its project is suspended.
INVALID_SUBSCRIPTION	422	The body does not match the subscription shape, or the endpoint is not on a supported push service.
RATE_LIMITED	429	More than 60 connect requests a minute from one IP address, counting both connect endpoints.
INTERNAL_ERROR	500	Something failed on Push's side. It is safe to retry.

WarningNotifications for this browser are shown by Push's service worker on meslzy.com. A subscription made on another site's service worker receives messages it does not know how to display.

Example#

⫻

curl

curl https://api.meslzy.com/push/v1/connect/cl_4Jr8xT2mQ9vLw7NcPz3sKd6YbHf1Ae5U \  -H "Content-Type: application/json" \  -d '{  "subscription": {    "endpoint": "https://fcm.googleapis.com/fcm/send/eXk9…",    "keys": {      "p256dh": "BNcRdreALRFXTkOOUHK1EtK2wtaz5Ry4YfYCA_0QTpQtUbVlUls0VJXg7A8u-Ts1XbjhazAkj7I99e8QcYP7DkM",      "auth": "tBHItJI5svbpez7KI4CCXg"    }  }}'

⫻

200 OK

HTTP/1.1 200 OKContent-Type: application/jsonX-Request-Id: req_0199b1c27a4e7c3d9f1e2b6a8d4c5e11
{  "browserId": "0198f0aa-1c2d-7e3f-9a4b-5c6d7e8f9012",  "recipientId": "0198f09e-4b1a-7c2d-8e3f-4a5b6c7d8e9f",  "eventToken": "kq3Vd9xZr2Lm8Tn4Bw6Yc1Hs7Pf5Gj0Ae2Ui9Ok4Rt8"}

NoteThe endpoint above is shortened. Real endpoints are long, opaque URLs issued by the browser.