# Access Control

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

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

## Access Levels

Synento supports three access modes for sessions:

| Mode | Who Can Replay | Auth Required? | Use Case |
|------|----------------|----------------|----------|
| **Private** (default) | Connection token holders only | Yes — API key + valid JWT | Internal meetings, customer calls |
| **Public** | Anyone with the session ID | No — completely open | Demo sessions, public webinars |
| **Expiring Link** | Anyone with the unique URL | No — token-based (time-limited) | Share with external parties temporarily |

## Making a Session Public/Private

Toggle visibility via the update endpoint:

```bash
# 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
```bash
curl "https://api.synento.com/v1/public/sessions/{sessionId}/playback?from_ts=0&window_size=30000"
```

### Public Timeline Metadata
```bash
curl https://api.synento.com/v1/public/sessions/{sessionId}/playback/timeline
```

### Public Replay with Token Fallback
```bash
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:

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

Response:
```json
{ "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

| Parameter | Default | Max Value | Description |
|-----------|---------|-----------|-------------|
| `expires_in_minutes` | Platform default | 43200 (30 days) | TTL of the link in minutes |

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):

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

Response (no project IDs exposed for privacy):
```json
{ "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:

```html
<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](https://synento.com/docs/guides/sdk.md) 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:

| Credential | Held by | Reaches |
|---|---|---|
| Dashboard session | You, in a browser | Everything in your organisation |
| API key `sk_live_…` | Your servers | Your organisation's management API, and sessions in its project |
| Restricted key `rk_live_…` | Your app, often written there by an agent | One project: create sessions, mint connection tokens, read manifests — nothing else |
| Agent token `sat_…` / OAuth token | An MCP client | Only the MCP endpoint, only the projects and permissions you approved |
| Connection token | One participant's browser | One session, as one participant, for an hour |

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](https://synento.com/docs/guides/mcp.md) for the agent credentials.