Skip to main content

​
RCS Demo Videos: Permanent Share Links

Carrier verification of an RCS agent requires a video_url: a recording of a real conversation with the agent that a human reviewer opens days or weeks after you submit. Every ordinary signed URL Orbit produces for an uploaded object is clamped to seven days, so a reviewer who opens such a link late gets a 403 and the submission fails with no way to tell why. Orbit can instead host the video behind a permanent link that never expires, stays revocable, and hands every visitor a freshly signed URL. This page covers minting that link, what the link is, revoking it, and putting it into a verification submission. For the rest of the submission contract read the RCS brand verification KYC walkthrough; for what happens after a submission is accepted read RCS verification corrections and screenshot retention. A seven-day clamp is the right shape for a dashboard player or a campaign asset and the wrong shape for carrier review: the reviewer is a person with a queue, and a link submitted on a Monday can be opened two weeks later. Past the clamp the object store answers 403, and the verification fails on a link that looked fine when you submitted it. The share link removes the expiry without making the object public. POST /api/v1/files/{file_id}/share mints a signed token; the public page behind that token verifies it and mints a fresh short-lived signed URL on every request. The link you file with the carrier never expires; the signed URL behind it always has minutes left on it. Your storage stays private, and the public surface is one link you can withdraw. Mint a link for any video you already uploaded:
The request takes no body, and there is deliberately no TTL parameter: an expiring demo-video link is exactly the defect this feature removes, so expiry is not a knob. Revocation (section 5) is the control. The response:
  • share_url is the page a human opens: an HTML video player. This is the value to put in video_url.
  • raw_url redirects to a freshly minted signed URL for the bytes. Use it where something needs the video file itself: an embedded <video src>, a download, or a fetcher that checks Content-Type: video/*.
Minting requires the files:write scope and an owner, admin, or developer role. The file id is the file_… identifier from the upload response, from GET /api/v1/files, or from the asset’s row in the dashboard under Developer > Media. Errors: 404 when the id does not exist in your workspace, and 422 when the file is not a shareable video. Only video/mp4 and video/3gpp can carry a permanent link. The token appended to both URLs is base64url(JSON payload) + . + base64url(HMAC-SHA256 signature). The payload carries the file id, your tenant, and a revocation nonce; the signature is computed with a server-side secret. It is the same signed-token shape Orbit uses for call-recording share links. The resolver verifies the signature on every request and refuses any token whose payload was edited. Nothing in the link is secret; the link is a bearer grant whose lifetime is governed by revocation, not by secrecy. The token carries no issued-at time, so minting twice for the same video returns the same share_url, byte for byte, until you revoke. Copy the link once, submit it, and re-read it from the API weeks later to double-check what you filed: the two strings reconcile exactly, so there is never a question of which link the carrier holds. Revoke with DELETE /api/v1/files/{file_id}/share:
Revocation rotates the video’s revocation nonce, and every outstanding link for that file stops resolving in the one call, including copies you minted earlier and pasted elsewhere. Mint again afterwards to start a fresh link. This is also why the platform does not simply sign a ten-year URL instead: a signed URL, once handed out, cannot be withdrawn.

​
6. Submit it for verification

Paste share_url into video_url on the verification submission. The field accepts at most 2,048 characters; a share URL lands near 280, so it fits with room to spare.
data is a JSON string; screenImages[] carries the conversation screenshots (up to 10, 5 MB each). The full multipart contract, including the KYC document parts and country rules, is in the KYC walkthrough. A submission without video_url is refused with a 422 before anything reaches the carrier, and the same field is required on a correction, so the link you mint once keeps serving resubmissions.

​
7. Tenant isolation

Your tenant identifier travels inside the signed payload. Editing the link to point at another workspace’s object invalidates the signature, and a link never resolves an object outside the workspace that minted it. A share link exposes exactly one object; it confers no list or read access to anything else in your media library.

​
8. When not to use it

The permanent link is built for one consumer: a human reviewer who opens it at an unpredictable time. For everything else keep the ordinary short-lived URLs:
  • Campaign and template media keep using the signed URLs the upload returns.
  • Serving bytes from your own backend keeps using GET /api/v1/files/{file_id}/presign, which mints a signed URL with a caller-chosen TTL.
If you are tempted to put a share link into a marketing message or a public web page, use a presigned URL instead: short-lived by default, renewed by you when needed, and revocable by simply letting it lapse.

​
9. Operator checklist

  • A verification failed because the video link 403s. The URL you submitted was a signed URL past its seven-day clamp. Mint a share link and resubmit with it as video_url.
  • The link must die today. DELETE /api/v1/files/{file_id}/share stops every copy of it in one call; mint again for a fresh link.
  • 422 while minting. The object is not video/mp4 or video/3gpp. Re-encode, upload, then mint.
  • Two different links for one video? Impossible before a revocation, because the URL is deterministic. If two strings exist, the older one predates a revocation; use the newer one.