Integrating with Supercast

If you're building an application that acts on behalf of Supercast users — for example, a third-party tool where creators connect their Supercast account — you can register an OAuth application to obtain user-authorized access tokens.

This is more involved than generating a token from Settings → API, but gives your application access to any channel a user manages, without requiring them to copy and paste tokens manually.

Register an application

Contact Supercast to register your OAuth application. You'll receive:

• Client ID — a public identifier for your application
• Client Secret — a private secret used to exchange authorization codes for tokens; keep this secure and never expose it in client-side code

Authorization flow

Supercast uses the standard OAuth 2.0 Authorization Code flow.

Step 1 — Redirect the user to Supercast

Send the user to the Supercast authorization URL with your client credentials:

GET https://supercast.com/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &response_type=code
  &scope=public

Step 2 — Handle the redirect

After the user approves your application, Supercast redirects them to your redirect_uri with a short-lived authorization code:

https://your-app.com/callback?code=AUTHORIZATION_CODE

Step 3 — Exchange the code for a token

Make a server-side POST request to exchange the code for an access token:

curl -X POST https://supercast.com/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code=AUTHORIZATION_CODE \
  -d redirect_uri=YOUR_REDIRECT_URI

A successful response returns an access token:

{
  "access_token": "abc123...",
  "token_type": "Bearer",
  "scope": "public",
  "created_at": 1720000000
}

Step 4 — Make API requests

Use the access token as a Bearer token on subsequent requests:

curl https://app.supercast.com/api/v1/me \
  -H "Authorization: Bearer abc123..."

Call GET /api/v1/me first to identify which channels the user manages, then use the returned managed_subdomains to make channel-scoped requests.

Specifying a channel

When using a user-level OAuth token, most endpoints require you to specify which channel to act on. Pass the channel's subdomain in the X-CHANNEL-SUBDOMAIN header:

X-CHANNEL-SUBDOMAIN: your-channel-subdomain

Or as a query parameter:

GET /api/v1/episodes?channel_subdomain=your-channel-subdomain

Scopes

Request only the scopes your application needs.