Supporting Cast SDK v1.0

The most recent documentation & SDKs are available at http://developers.supportingcast.fm/

Signed Tokens

Overview

Supporting Cast uses signed tokens to secure access to your podcast feeds.

The included SDK libraries and examples will allow you to generate signed tokens directly on your server. If the language you are using is not available, you can contact us at help@supportingcast.fm and we will create one for you.

Available Languages

• PHP
• Python
• Ruby

Requirements

In order to generate a signed URL, you need 4 pieces of information:

1. The member_id of the member you are giving the URL to
2. The id of the feed
3. A Secret Key and associated Secret Key ID
4. Your Supporting Cast domain (e.g. mysite.supportingcast.fm)

To get a Secret Key:

1. Login as a manager on your Supporting Cast Site
2. Go to "Developers" -> "Signing Keys" in the left sidebar
3. Click "Add Signing Key" and follow the instructions
4. Save the Secret Key & Secret Key ID to a safe location

If your secret key is compromised

If your secret key is compromised (by a hacker, rogue employees, mistake, etc.) you will need to switch to a new Secret Key and revoke the compromised one.

Warning: If you revoke a signing key, then any URLs you signed with that key will also be revoked.

• Your users will need to update their feed URLs.
• No Invalidation webhooks will be fired since this is a not a user-specific invalidation.
• This will not generate any emails warning your members. You are responsible for that.
• Users will get an 'Access Revoked' Dynamic Message when they try to access old feeds (if you have one configured).

Revoking a key

1. Login as a manager on your Supporting Cast Site
2. Go to "Developers" -> "Signing Keys" in the left sidebar
3. Click 'Add Signing Key' and follow the instructions to create a New secret key
4. Configure the New secret key & ID in your application and make sure it's in use before proceeding!
5. Find the Compromised Signing Key you want to revoke (by ID)
6. Click revoke

Technical Details

Signed Tokens use a json payload signed with a HMAC SHA256 Hash. The Hash should be generated as a Hex Digest.

1. Build the JSON payload

The Json Payload should contain the following keys (compressed, with no spaces or line feeds)

{
  "t": "p",
  "c": <<Feed_ID>,
  "u": "<<Member_ID>>",
  "r": "m",
  "d": <<Unix_Timestamp>>,
  "k": <<Secret_Key_ID>>
}

t (Type) : 'p' for Podcast Feed

c (Content ID) : Feed ID

u (User) : the member_id

r (Role) : 'm' for member

d (Date) : Integer Unix Timestamp (e.g. Seconds since the epoch)

k (Key ID) : The Secret Key ID you will use to sign the message

2. Sign the JSON payload

The Message Signature is appended to the end of the JSON string with a '|'

<<JSON>>|<<SIGNATURE>>

For Example:

{"t":"p","c":"1","u":"2","r":"m","d":"1587611343","k":3}|d5afac3d5ce7b5393c5983935d21febfdfdad9ba2872de3dca12357f60fbe645

3. Base64 encode the entire string

The entire <<JSON>>|<<SIGNATURE>> string should be base64 encoded

4. Build the URL with the token

http://<<Domain>>/content/<<Base64_Encoded_String>.rss

Webhook Validation

Overview

Webhooks are signed with the same secret key you use to sign tokens.

When a Signing Key is configured on your account, two additional headers will be included on every webhook request:

Webhook-Signature The Signature Webhook-Signature-Key-ID The ID of the Signing Key used

The included 'verify_webhook' example files will show you how to verify this signature.