Access Control

Manage who can access your sessions: private, public, and expiring links.

Access Levels

Synento supports three access modes for sessions:

Making a Session Public/Private

Toggle visibility via the update endpoint:

# Make public — anyone can replay
curl -X PUT https://api.synento.com/v1/sessions/{sessionId}/visibility \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -d '{"is_public": true}'

# Make private — only token holders can replay (default)
curl -X PUT https://api.synento.com/v1/sessions/{sessionId}/visibility \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -d '{"is_public": false}'

Response: {"data": true, "error": null} (reflects the updated visibility state).

Public Session Access Endpoints

When a session is public (is_public = true), these endpoints work without authentication:

Public Playback Window

curl "https://api.synento.com/v1/public/sessions/{sessionId}/playback?from_ts=0&window_size=30000"

Public Timeline Metadata

curl https://api.synento.com/v1/public/sessions/{sessionId}/playback/timeline

Public Replay with Token Fallback

curl "https://api.synento.com/v1/public/sessions/{sessionId}/replay?token=EXPIRING_TOKEN&from_ts=0"

This endpoint checks for an expiring replay token first, then falls back to the public session check if no valid token is provided.

Expiring Replay Links

Create time-limited replay links for sharing with external parties:

curl -X POST https://api.synento.com/v1/sessions/{sessionId}/replay-links \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -d '{"expires_in_minutes": 60}'

Response:

{ "data": {
  "link": "https://host/v1/public/sessions/{sessionId}/replay?token=abc123",
  "token": "abc123",
  "expires_at": "2025-01-15T13:00:00.000Z"
}, "error": null }

Link Details

The link works with all playback query parameters:

https://host/v1/public/sessions/{sessionId}/replay?token={token}&from_ts=5000&window_size=60000

When the token expires, access is denied (401 or 403). Links are automatically invalidated when the session's recording is deleted.

Public Session Catalog

Anyone can browse publicly accessible sessions (no auth required):

curl https://api.synento.com/v1/public/sessions

Response (no project IDs exposed for privacy):

{ "data": [
  { "id": "...", "name": "Public Demo",
    "created_at": "...", "started_at": "...", "ended_at": "..." }
], "error": null }

Sessions are sorted by created_at DESC. Only metadata is included — no project or organisation data.

Embedding Public Sessions

Public sessions can be embedded via an iframe with the replay endpoint:

<iframe 
  src="https://your-server.com/v1/public/sessions/{sessionId}/replay?from_ts=0&window_size=30000"
  width="640" height="360">
</iframe>

For a richer experience, use the Player SDK with the public playback endpoints.

Security Notes

1. Public sessions are fully visible — anyone with the session ID can replay them
2. Expiring links degrade to public access if the underlying session is marked is_public = true
3. Session IDs are not secrets — access control relies on is_public flag and token validation, not ID obscurity
4. Replay tokens are independent of connection tokens — use POST /v1/sessions/:sessionId/replay-links for sharing, not /connection endpoints

Credentials

Who can do what to your account, from widest to narrowest:

Give each piece of code the narrowest one that works. An app that only creates sessions and lets people join needs no more than a restricted key. See Connect your agent for the agent credentials.