Push Subscriptions

Device-facing endpoints, authenticated with the app’s public key (grv_pub_). Send it as X-API-Key or Authorization: Bearer — the header is checked in that order, and query strings are never accepted. The app’s secret key also works here; the public key never works on publish. Rate limit: 240 requests per minute per key. Exceeding it returns 429 with a Retry-After header.

POST /v1/apps/:appID/subscriptions

{
  "channel": "order:42:status",
  "deviceToken": "a1b2c3...",
  "tokenType": "alert",
  "environment": "production",
  "activityID": null,
  "metadata": { "locale": "en_US" },
  "previousToken": null
}

Field	Type	Required	Description
`channel`	`string`	Yes	Opaque channel name, 1–255 printable characters, not only whitespace
`deviceToken`	`string`	Yes	Hex APNs token, 16–512 characters, even length. Normalized to lowercase
`tokenType`	`string`	Yes	`alert`, `liveactivity-start`, or `liveactivity-update`
`activityID`	`string`	For `liveactivity-update`	The Live Activity this update token belongs to, max 255 characters
`environment`	`string`	No	`sandbox` or `production` — overrides the app’s default for this subscription
`metadata`	`object`	No	String key-value data stored with the subscription
`previousToken`	`string`	No	A rotated token — all its same-type subscriptions are deleted (push-to-start rotation)

Subscriptions upsert by (app, deviceToken, tokenType, channel): re-registering updates rather than duplicates. Returns 201 on create, 200 on update. Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "channel": "order:42:status",
  "deviceToken": "a1b2c3...",
  "tokenType": "alert",
  "activityID": null,
  "environment": "production",
  "metadata": { "locale": "en_US" },
  "createdAt": "2026-07-26T12:00:00Z"
}

Errors

Status	Meaning
400	Invalid channel, device token, or a `liveactivity-update` subscription without `activityID`
401	Missing or invalid API key
429	Rate limit exceeded for this key

List a device’s subscriptions

GET /v1/apps/:appID/subscriptions?deviceToken=<hex>

Returns the device’s subscriptions, oldest first — useful for reconciliation after reinstall or token rotation. deviceToken is required; omitting it returns 400.

{
  "subscriptions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "channel": "order:42:status",
      "deviceToken": "a1b2c3...",
      "tokenType": "alert",
      "activityID": null,
      "environment": "production",
      "metadata": null,
      "createdAt": "2026-07-26T12:00:00Z"
    }
  ]
}

Unsubscribe

DELETE /v1/apps/:appID/subscriptions

{
  "deviceToken": "a1b2c3...",
  "channel": "order:42:status",
  "tokenType": "alert"
}

With channel (optionally narrowed by tokenType), removes the matching subscriptions. With deviceToken alone, wipes every subscription for the device (logout). Returns { "removed": <count> }.

Overview

Attestation

Platform

Feedback

Feature Flags

Custom Claims

Analytics

Webhooks

Organization

Push

Entitlements

Visual Regression Testing

Auth

Push Subscriptions

List a device’s subscriptions

Unsubscribe

​Subscribe

​List a device’s subscriptions

​Unsubscribe

Subscribe

List a device’s subscriptions

Unsubscribe