Synento docs
Guides

Access control

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

View as Markdown

Three modes: private (default), public, and a time-limited replay link.

Access levels

ModeWho can replayAuth required?Use case
Private (default)Your servers (API key), your team in the dashboard, and anyone you give a replay connection tokenYes: API key, dashboard sign-in, or a token you mintedInternal meetings, customer calls
PublicAnyone with the session IDNo: completely openDemo sessions, public webinars
Expiring linkAnyone holding the link's tokenNo: the token is the credential (time-limited)Share with external parties temporarily

Every way of replaying counts toward your replay allowance, public sessions and replay links included. See Recordings & Replay.

Making a session public or private

Toggle visibility with your API key:

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

# Make private again (the default)
curl -X PUT https://api.synento.com/v1/sessions/{sessionId}/visibility \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"is_public": false}'

Response: {"data": {"id": "<sessionId>", "is_public": true}, "error": null} (the updated visibility state).

Public session access endpoints

When a session is public (is_public = true), these endpoints work without authentication. A private or unknown session answers 404.

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 manifest

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

Public replay with token fallback

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

With a token, this endpoint serves the session if the token is valid and unexpired, whether or not the session is public. Without a token, it serves only public sessions. An invalid or expired token is refused with 404 even if the session is public. Leave token out to read a public session.

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" \
  -H "Content-Type: application/json" \
  -d '{"ttl_minutes": 60}'

Response:

{ "data": {
  "id": "5b0c…",
  "link": "https://api.synento.com/v1/public/sessions/{sessionId}/replay?token=abc123",
  "token": "abc123",
  "expires_at": "2025-01-15T13:00:00.000Z"
}, "error": null }

link is the replay endpoint with the token filled in. Without from_ts it returns the recording's first window; pass the previous window's end_ts as from_ts to read on. It returns JSON for your own player, not a web page.

ParameterDefaultMax valueDescription
ttl_minutes6043200 (30 days)How long the link works, in whole minutes (1–43200)

The link works with the playback query parameters from_ts and window_size (milliseconds; the window defaults to 30000 and is at most 60000):

https://api.synento.com/v1/public/sessions/{sessionId}/replay?token={token}&from_ts=5000&window_size=60000

When the token expires, the endpoint answers 404 (replay link expired). Links stop working when the session is deleted. To end one link early, revoke it by the id it was created with:

curl -X DELETE https://api.synento.com/v1/sessions/{sessionId}/replay-links/{id} \
  -H "Authorization: Bearer sk_live_xxxxx"

Synento stores only a hash of each link's token, so a lost link cannot be looked up again: create a new one.

Public session catalog

Anyone can list a project's public sessions (no auth required). The project_id query parameter is required:

curl "https://api.synento.com/v1/public/sessions?project_id={projectId}"

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, at most 100 of them. Only metadata is included, not project or organisation data.

Embedding public sessions

Synento does not host an embeddable replay page: the public endpoints return JSON playback data, not something an <iframe> can show. To show a public session on your site, have your front end read the public endpoints above and render the media itself. See Recordings & Replay for the playback format and the @synento/player SDK, which plays video and audio.

Security notes

  1. Public sessions are fully visible. Anyone with the session ID can replay them.
  2. Making a session public makes it open to everyone, whether or not you also issued expiring links for it.
  3. Session IDs are not secrets. Access control relies on the 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:

CredentialHeld byReaches
Dashboard sessionYou, in a browserYour organisation, as far as your role (owner, admin or member) allows
API key sk_live_…Your serversEverything video in your organisation through the API: projects, sessions, webhooks, keys, usage. Creating, replaying and deleting sessions is limited to the key's own project. People and money are not its business: inviting or removing members, changing roles, renaming the organisation, checkout and the billing portal need a signed-in owner or admin, and a key gets 403
Restricted key rk_live_…Your app, often written there by an agentOne project: create sessions, mint connection tokens, read manifests. Nothing else
Agent token sat_… / OAuth tokenAn MCP clientOnly the MCP endpoint, only the projects and permissions you approved
Connection tokenOne participant's browserOne session, as one participant, for an hour

Treat an sk_live_ key as an organisation-wide credential: it can mint keys for, and move itself to, any project in the organisation. That is why only owners and admins can create one. A member gets 403, since a key would let them do what their role does not (deleting projects, shortening retention). When you remove someone from the organisation, the sk_live_ and rk_live_ keys they created are revoked and their pending invitations withdrawn. Keys created before October 2026 have no recorded creator and are kept, so rotate those yourself.

Signing out ends your sessions on every device, and so does changing or resetting your password.

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.

On this page