Supercast API Example

A minimal Sinatra app that demonstrates the Supercast superapp OAuth authorization code flow. It is intended for two audiences:

• Developers building a Supercast integration who want a working reference implementation of the OAuth flow, token storage, and API calls.
• Developers testing their own superapp credentials against the real Supercast API before building their own integration.

What is a superapp?

A regular Supercast OAuth application is tied to a single channel. A superapp is an OAuth application that can act on behalf of any channel or network whose owner has authorized it — the credentials are the same regardless of which channel you're accessing. The channel is specified per-request via a subdomain query parameter.

This is the right model for third-party tools, analytics platforms, publisher dashboards, or anything else that needs to work across multiple Supercast channels.

Prerequisites

• Ruby 3.0 or later
• Bundler (gem install bundler if you don't have it)
• A Supercast superapp created in the admin panel (see below)

Step 1 — Create a superapp

Go to /admin/oauth_applications in the Supercast admin panel and create a new OAuth application. Make sure the Superapp option is enabled.

Register the redirect URI that matches where you're running this app:

Environment	Redirect URI
Development	http://localhost:4000/auth/callback
Production	https://your-domain.com/auth/callback

After saving, copy the Application UID (client ID) and Secret.

Step 2 — Configure the app

Copy the example env file and fill in your credentials:

cp .env.example .env

Edit .env:

SUPERCAST_CLIENT_ID=<your app's uid>
SUPERCAST_CLIENT_SECRET=<your app's secret>
SUPERCAST_ENV=development        # or "production"
REDIRECT_URI=http://localhost:4000/auth/callback
SESSION_SECRET=<long random string>
PORT=4000

See the Environment variables table below for the full list.

Step 3 — Install and run

bundle install
bundle exec ruby app.rb

Open http://localhost:4000.

How the OAuth flow works

1. Click Connect to Supercast. The app builds an authorization URL with your client ID, the redirect URI, a public write scope, and a CSRF state token, then redirects the user to the Supercast OAuth consent screen.

2. The channel owner (or any user you want to authorize) approves the request on the Supercast side.

3. Supercast redirects back to /auth/callback with a short-lived authorization code and the state token. The app verifies the state, then exchanges the code for an access token and refresh token by posting to /oauth/token.

4. Tokens are stored in the encrypted session cookie. The access token is set to expire 60 seconds before its actual expiry to give the refresh a margin.

5. On the dashboard, enter the subdomain of the channel or network you want to query (for example, my-podcast). This is scoped per-request — you can change it at any time.

6. Click any of the three endpoint cards to fire a live API call. The raw JSON response is shown with pagination (20 items per page).

If the access token has expired by the time you make an API call, the app automatically exchanges the refresh token for a new access token before retrying. If the refresh also fails (for example, the token was revoked), you are prompted to re-authorize.

Environment variables

Variable	Default	Description
SUPERCAST_CLIENT_ID	(required)	OAuth application UID from the admin panel
SUPERCAST_CLIENT_SECRET	(required)	OAuth application secret from the admin panel
SUPERCAST_ENV	development	development → https://app.supercast.test, production → https://app.supercast.tech
REDIRECT_URI	http://localhost:4000/auth/callback	Must match exactly what is registered in the admin panel (protocol, host, and port included)
SESSION_SECRET	random	Used to sign the session cookie — set a stable value so sessions survive restarts
PORT	4000	Port the Puma server listens on

API endpoints exercised

Endpoint	API call	What it returns
Subscribers	GET /api/v1/subscribers?subdomain=<subdomain>	Subscriber list for the channel or network
Episodes	GET /api/v1/episodes?subdomain=<subdomain>	Episode list for the channel
Charges	GET /api/v1/charges?subdomain=<subdomain>	Charge (payment) history for the channel

All three endpoints accept page and per_page parameters. This app requests 20 items per page and renders Prev / Next pagination links.

Development vs production

Set SUPERCAST_ENV=development to point at a local Supercast instance running at https://app.supercast.test. In this mode, SSL certificate verification is disabled — puma-dev uses a self-signed certificate, so verification would fail. This flag has no effect on the token or API logic; it only changes the base URL and the SSL setting.

Set SUPERCAST_ENV=production to point at https://app.supercast.tech with full SSL verification. This is what you want when testing against real channel data or validating credentials before going live.