Notify API reference

Notify API · Recipient-Tokens

post/v1/workspaces/{workspace_id}/recipient-tokensAuth

Mint a recipient token

Returns a short-lived token (default 1 hour, at most 24 hours) that lets one recipient read their inbox, register devices, manage their preferences and open the real-time stream through the client API (`/v1/client/…`). Mint it on your backend with your API key after you have signed the user in, and hand it to the app or browser: your secret key never ships in an app. A recipient that does not exist yet is created (with the `upsert` fields if given). Limited to 3,000 mints per minute per workspace: cache a token per user for most of its lifetime. Not idempotent by design (each call returns a fresh token), so it takes no `Idempotency-Key`.

Path parameters

workspace_id*string · uuid

Id of the workspace.

Request body

recipient*string

Your user id for the recipient (`external_id`). A recipient that does not exist yet is created (bare, or with the `upsert` fields), so you can mint at sign-in without a separate call.

Example: "user_123"

scopesarray

What the token allows. Default: every scope. Narrow it for a surface that only reads the inbox, for example.

Example: ["inbox:read","stream"]

ttl_secondsinteger

Lifetime in seconds (60 to 86,400). Cache the token per user for most of its life instead of minting on every page load.

upsertobject

Profile fields to set on the recipient while minting (created or existing). Left out: the profile is not changed.

Response · 201 The token.

token*string

The recipient token (an RS256 JWT). Send it as `Authorization: Bearer <token>` to the client API (`/v1/client/…`) from the recipient's app or browser. Keep it in memory, never in a URL or browser storage.

Example: "eyJhbGciOiJSUzI1NiIsImtpZCI6InJzMjU2LWV4YW1wbGUifQ.eyJzdWIiOiIuLi4ifQ.c2lnbmF0dXJl"

expires_at*string · date-time

When the token stops working; mint a new one before then.

scopes*array

The scopes the token carries.

recipient_id*string · uuid

The recipient's Notify id.

external_id*string

Your user id for the recipient.

Example

Request

POST https://api.notify.productcraft.co/v1/workspaces/{workspace_id}/recipient-tokens
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "recipient": "user_123",
  "scopes": [
    "inbox:read",
    "stream"
  ],
  "ttl_seconds": 0,
  "upsert": {}
}

Response

{
  "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InJzMjU2LWV4YW1wbGUifQ.eyJzdWIiOiIuLi4ifQ.c2lnbmF0dXJl",
  "expires_at": "2026-01-01T00:00:00.000Z",
  "scopes": [
    "inbox:read"
  ],
  "recipient_id": "00000000-0000-0000-0000-000000000000",
  "external_id": "string"
}