The restricted access system allows you to grant authorized members access to restricted clips and playlists using secure access tokens, you can learn more about restricted access here.
Whilst you can generate and share restricted content from the Omny Studio UI, it is also possible to programmatically generate secure URLs with access tokens to share and play restricted content on custom players, apps or websites behind a paywall.
You can do this via the Omny Studio Management API.
Use cases
For example, if you have a paywalled app or website, you can programmatically generate access tokens to provide your users access to:
Podcast RSS URLs for restricted playlists
Embed players for restricted clips and playlists
MP3 download URLs for restricted clips
Access tokens
Access tokens can be appended to various URLs including clip MP3 download URLs, embed player iFrame URL, podcast RSS URLs using the accessToken URL parameter to authorize access to restricted content.
For example, a restricted playlist RSS feed can be accessed with https://omny.fm/.../podcast.rss?accessToken=eyJhbGciOiJIUzId1...
A restricted clip embed can be shared with
<iframe src="https://omny.fm/.../embed?accessToken=eyJhbGciOiJIUzI1NiI...
A restricted clip MP3 download URL can be access with
https://omnystudio.com/.../audio.mp3?accessToken=eyJhbGciOiJIUzI1NiIs...
An invalid access token or using a revoked access token will return an error page.
Generating access tokens
JSON Web Token
Omny Studio's restricted access tokens use the JSON Web Token (JWT) standard. You can read more about JWT's and find popular code libraries for parsing and generating JWT at jwt.io.
The accessToken
JWT is comprised of the following structure encoded in a Base64 URL encoded string.
Header
{
"kid": "[YOUR PROGRAMMATIC SIGNING KEY ID]",
"alg": "HS256",
"typ": "JWT"
}
The
kid
is your programmatic signing key ID which you can find in the Program Settings > Restricted Access UI or retrievable via the Management APIThe JWT standard headers
alg
andtyp
must be set
Payload or claims
{
"playlist": "[PLAYLIST ID]", // or "clip": "[CLIP ID]"
"key": "W2J4n19zhkKjYRVvb2uU1g"
}
A
playlist
orclip
claim specifying the GUID of the playlist or clip to access (it must match the content URL being accessed)The
key
claim is the restricted members' key which you can find in the Program Settings > Restricted Access UI or retrievable via the Management API.Optionally, you can set an
ads
claim to override if dynamic ads injection should be applied to the downloaded content. A value of1
will enable ads, and a value of0
will disable ads. If no value is provided, it will fallback to the "Disable dynamic ad insertion for restricted member downloads" setting on the clip or playlist.
Signature
Your JWT signature should be signed using the algorithm specified in the header. Using the standard HMAC-SHA256 algorithm, it should be signed as follows
HMACSHA256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
[YOUR PROGRAMMATIC SIGNING SECRET]
)
The signing secret is the programmatic signing secret which you can find the Program Settings > Restricted Access UI or retrievable via the Management API.
You can find an example of a valid access token here.
Regenerating keys and secrets
If the individual restricted member key or your program's programmatic signing secret are ever leaked publicly, you can reset/regenerate both in the Omny Studio UI and Management API.
It is important to note that all previously generated access tokens will become invalid after regenerating either the member key or programmatic signing secret, especially users who subscribed to a restricted RSS feed will no longer be able to refresh their feed.
Managing restricted members
Due to privacy reasons, Omny Studio does not store any personally identifiable information about restricted members.
We encourage you to generate a restricted member for each of your service's paywall subscribers or users and correlate them using the member ID.
The Management API allows you to create and delete restricted members and regenerate keys programmatically. You can also pause a member's access to their individual feed. View the Management API documentation to learn more.