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.

{
  "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 API
The JWT standard headers alg and typ must be set

Payload or claims

{
  "playlist": "[PLAYLIST ID]", // or "clip": "[CLIP ID]"
  "key": "W2J4n19zhkKjYRVvb2uU1g"
}

A playlist or clip 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 of 1 will enable ads, and a value of 0 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. V iew the Management API documentation to learn more.