Authentication

The Supercast API supports two authentication methods: manual access tokens and OAuth 2.0. Both methods use Bearer token authentication — include your access token in the Authorization header of every request:

Authorization: Bearer YOUR_ACCESS_TOKEN

Manual Access Tokens

Manual access tokens are long-lived credentials you generate directly from the Supercast dashboard. They do not expire and are best suited for server-to-server integrations, scripts, and tools where you control the environment.

Generating a token

1. Log in to the Supercast dashboard.
2. Navigate to Settings → API.
3. Click Generate Token.
4. Copy the token — it will not be shown again.

Using a token

GET https://api.supercast.tech/v1/episodes
Authorization: Bearer YOUR_ACCESS_TOKEN

Revoking a token

Tokens can be revoked from the same API settings page. Revocation is immediate.

OAuth 2.0

OAuth 2.0 is the recommended authentication method when your application acts on behalf of a Supercast channel or network owner. Tokens issued via OAuth expire after 2 hours and must be refreshed using a refresh token.

Available grant types

Scopes

Authorization Code flow

Use this when your integration needs a channel or network owner to grant your application access.

Step 1 — Redirect the user to the authorization endpoint

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

The user will be prompted to log in (if not already) and authorize your application.

Step 2 — Exchange the authorization code for tokens

After the user approves, Supercast redirects to your redirect_uri with a code query parameter. Exchange it for an access token:

POST https://supercast.tech/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=YOUR_REDIRECT_URI
&code=AUTHORIZATION_CODE

Response:

{
  "access_token": "abc123...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "xyz789...",
  "scope": "public write",
  "created_at": 1716220800
}

Client Credentials flow

Use this for server-to-server integrations where no user interaction is required. Your application authenticates directly with its client credentials.

POST https://supercast.tech/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&scope=public+write

Response:

{
  "access_token": "abc123...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "public write",
  "created_at": 1716220800
}

Refreshing an access token

OAuth access tokens expire after 2 hours. Use the refresh_token from the original token response to obtain a new access token without requiring the user to re-authenticate.

POST https://supercast.tech/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&refresh_token=YOUR_REFRESH_TOKEN

Response:

{
  "access_token": "newtoken456...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "newrefresh012...",
  "scope": "public write",
  "created_at": 1716228000
}

Note: Each refresh issues a new refresh token. Discard the old one and store the new pair.

Choosing an authentication method