> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Share a video or voice recording with the public player

> Mint a time-limited, unauthenticated playback link for a completed video-room recording, send it to a supervisor or customer, revoke it at any time, and read the share-access audit trail.

# Share a video or voice recording with the public player

After a video room ends, the composite recording lands in your [recording library](/voice/recording-library). The dashboard can mint a public, time-limited link that opens in a stock browser with no Orbit login required — the same parity you get from Zoom or Teams recording shares. Use it when you need to hand a finished recording to someone who does not have a dashboard seat, such as a supervisor reviewing a QA evaluation or a customer receiving a telehealth consultation recap.

This guide covers the share surface in the dashboard, what the link carries, how to revoke it, and how to read the audit trail.

<Note>
  The public player is for **completed video-room recordings** only. Live broadcasts use the [WHEP guest player](/guides/whep-guest-player), and voice-only call recordings are shared through the [recordings API post-call pipeline](/guides/recording-lifecycle-operations).
</Note>

## Where the share surface lives

Open a completed video-room session and scroll to the **Recording** card. When the egress has finalized a shareable recording, you will see **Share recording**.

1. Go to **Voice → Video → Sessions** and open the session you want to share.
2. In the **Recording** card, click **Share recording**.
3. The dashboard calls `POST /api/v1/recordings/{id}/share` and copies the resulting public link to your clipboard.
4. Paste the link into an email, ticket, or chat message to the recipient.

The link is created with a default lifetime of **7 days**. You can request a shorter or longer lifetime through the API by sending `expires_in_seconds` in the request body. Accepted values are clamped server-side to between **5 minutes** and **30 days**; anything outside that band is rounded to the nearest limit.

### Scope constraints

The share surface is a tenant-owned control:

* Only completed video-room recordings can be shared. In-progress rooms, voice call legs, and tombstoned recordings return an error.
* Creating or revoking a link requires the `video:write` scope (owner, admin, or developer role in the dashboard).
* Viewing the shared recording requires no authentication; the grant is carried entirely inside the signed URL.

## The player URL lifecycle

The URL handed to the recipient is a public resolve link:

```text theme={null}
https://api.orbit.devotel.io/public/recordings/{token}
```

The `{token}` is an HMAC-signed grant that contains:

| Field | Purpose |
| - | - |
| `recording_id` | The unified recording this link opens. |
| `tenant_schema` | The tenant that owns the recording, bound into the signature so a guest cannot edit the URL to reach another tenant. |
| `nonce` | A per-recording revocation nonce. The link stops working the moment the host rotates this nonce. |
| `issued_at` / `expires_at` | Unix timestamps that bound the link's validity. |

When the recipient opens the link, the resolver:

1. Verifies the HMAC signature and checks that the token has not expired.
2. Confirms the recording still exists, is a completed video-room artefact, and that the token's nonce matches the recording's current `share_nonce`.
3. Mints a short-lived signed URL to the underlying storage object and renders a minimal `<video>` player.

The recipient never sees the raw storage path or a long-lived credential. The embedded playback URL is the same \~1-hour signed URL the authenticated dashboard uses.

### Expiry and staleness

* **Expired link** — after `expires_at`, the resolver returns a 404 page stating the link is no longer valid. The host must create a fresh link.
* **Revoked link** — after the host clicks **Revoke links** or calls `DELETE /api/v1/recordings/{id}/share`, the recording's nonce rotates and every previously-minted link stops resolving immediately.
* **Deleted recording** — if retention or a manual deletion removes the recording, the link returns a 404.

## Revoke a shared link and read the audit log

Revocation is all-or-nothing for the recording: rotating the nonce invalidates every outstanding public link in one action, and new links can be minted afterwards.

### Revoke from the dashboard

In the same **Recording** card where you created the link, click **Revoke links** and confirm. The dashboard calls `DELETE /api/v1/recordings/{id}/share`.

### Revoke with the API

```bash theme={null}
curl -X DELETE "https://api.orbit.devotel.io/api/v1/recordings/rec_01J8ZC3NPA/share" \
  -H "Authorization: Bearer $ORBIT_API_KEY"
```

Response:

```json theme={null}
{
  "data": {
    "recording_id": "rec_01J8ZC3NPA",
    "revoked": true
  }
}
```

### Share-access audit log

Creating and revoking a link are both audit-logged. Open **Settings → Audit log** (or **Compliance → Audit log**, depending on your workspace layout) and filter for:

* `recording.share.created` — a host minted a public link.
* `recording.share.revoked` — a host rotated the nonce and revoked every outstanding link.

Each entry records the actor, the recording id, and the timestamp. The create entry also includes the requested TTL and the calculated expiry.

## Player inboxes: when playback events are logged

The public player itself is anonymous: anyone holding the link can watch without signing in. However, when the share workflow captures the recipient's email address — for example, by sending the link through an Orbit email step or by recording the recipient when the link is minted via the API — playback events are attributed to that email in the share-access log.

Playback events feed the [recording view analytics](/guides/recording-view-analytics) pipeline. If your workspace routes recording-share activity to the **Inbox**, a playback event logged against a known recipient email appears as an inbox entry tied to that recipient. This is useful for confirming that a supervisor reviewed a QA clip or that a customer watched a consultation recap.

Events are emitted as the viewer plays, pauses, seeks, and reaches the end of the recording. The analytics surface shows:

* unique viewers,
* concurrent viewers,
* total and average watch time,
* completion rate,
* a retention curve showing where viewers drop off.

## Example: share a voice QA evaluation with a supervisor

A contact-center supervisor needs to review an agent's video-room QA session.

1. Open **Voice → Video → Sessions** and locate the session.
2. Click **Share recording** to mint a 7-day link.
3. Paste the link into the supervisor's QA ticket.
4. The supervisor opens the link, watches the recording, and the playback event is logged against their email.
5. After the review window closes, click **Revoke links** to retire the URL.

## Example: share a video consultation recording with a customer

A healthcare provider wants to send a patient the recording of a telehealth consultation.

1. From the session detail, click **Share recording**.
2. Set a shorter lifetime — for example, 48 hours — by calling the API directly:

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/recordings/rec_01J8ZC3NPA/share" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expires_in_seconds": 172800}'
```

3. Send the returned `share_url` to the patient.
4. The patient watches the recap in a browser without installing the Orbit dashboard or SDK.
5. Playback appears in the share-access log, and the retention curve shows whether the patient watched the full consultation.

## Example: revoke after a dispute

A dispute arises about what was said in a shared session.

1. Open the session and click **Revoke links**.
2. Confirm; every previously shared URL for that recording stops working immediately.
3. Check the audit log for the `recording.share.revoked` entry to document when access was removed.
4. If a regulator or counsel still needs access, mint a new link with a tight TTL and share it only with them.

## API reference

| Action | Endpoint | Scope |
| - | - | - |
| Mint a public link | `POST /api/v1/recordings/{id}/share` | `video:write` |
| Revoke every public link | `DELETE /api/v1/recordings/{id}/share` | `video:write` |
| Resolve and play (guest) | `GET /public/recordings/{token}` | none |
| Report a playback event | `POST /api/v1/recordings/{id}/views` | `video:write` |
| Read engagement report | `GET /api/v1/recordings/{id}/views/report` | `video:read` |

## See also

* [Recording view analytics](/guides/recording-view-analytics) — measure who watched a shared recording and how far they got.
* [Operate the post-call recordings pipeline](/guides/recording-lifecycle-operations) — legal hold, integrity seals, captions, clips, and highlights.
* [WHEP in-browser guest player](/guides/whep-guest-player) — share a live broadcast, not a finished recording.
* [Recordings API reference](/api-reference/recordings) — legal holds, integrity seals, and share links.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.