Skip to main content

​
POST /api/v1/viewer-token

Create a short-lived JWT token scoped to specific filters. The token holder can only view events matching the specified constraints.

​
Request Body

​
tenant_id
string
Restrict to events for a specific tenant.
​
actor_id
string
Restrict to events by a specific actor.
​
ttl
integer
default:"3600"
Token lifetime in seconds. Minimum 60, maximum 86400 (24 hours).

​
Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2026-03-26T11:15:00Z"
}

​
Examples

curl -X POST https://getimmutable.dev/api/v1/viewer-token \
  -H "Authorization: Bearer imk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "org_7rT2xBc",
    "ttl": 7200
  }'

​
Embedding

Pass the token to your frontend to render the embedded viewer: 
<iframe
  src="https://getimmutable.dev/viewer?token=eyJhbGciOiJIUzI1NiIs..."
  width="100%"
  height="600"
  frameborder="0"
></iframe>
See the Embeddable Viewer guide for React component examples and TTL management.
Viewer tokens are read-only. They cannot be used to ingest events or access any write endpoints.