The Podchaser API has a variety of queries and mutations that allow you to lookup and make changes to specific user's data. In order to do so, a user needs to provide permission to your integration. To do this, we have our User Oauth system.
Setting Up Your Redirect URL
Before you begin allowing people to Oauth your app, you will need to set up a redirect URL. First, go to the API Settings page. Then, click the edit icon next to the "Redirect URL" setting. Enter in a valid URL.
This URL is where users will be redirected to after the Oauth permission page. This URL will receive the authorization code as a query parameter.
Be sure to click the save icon once you enter the redirect URL.
Identify Which Scopes You Need
For each of the main API mutations that affect user data, Podchaser has a unique "scope" that it requires your app to have permission for. For example, in order to add a rating for a user, your app would need user to grant permission for the "edit_ratings" scope.
Some of our scopes include:
- Adding and updating ratings: edit_ratings
- Adding and updating reviews: edit_reviews
- Following and unfollowing podcasts: edit_follows
- Creating and updating lists: edit_lists
- Mark episode as listened: edit_listens
You can view a mutation's needed scope by viewing its documentation.
Send User to OAuth Page
Once you have identified the scopes you need permission for, you will need to send the users to the Oauth page. This is the URL you will send users to:
You will replace the YOUR_CLIENT_ID with your own client id, the YOUR_REDIRECT_URL with your own redirect URL, and SCOPES with a space-separated list of scopes. For example, an example URL with a few scopes might look like:
https://www.podchaser.com/do-auth?client_id=random-fake-id&redirect_uri=https://podchaser.com&scope=read_ratings read_reviews edit_ratings edit_reviews edit_listens
On this page, the user will see a screen stating your app is requesting access with information about which scopes your app is wanting permission for.
Note: the redirect URL must exactly match the redirect URL you entered in the API settings.
Handling Authorization Code
Once the user authorizes your app, Podchaser will redirect the user to your redirect URL. Along with the redirect, Podchaser will add a
code query parameter which is set to a lengthy authorization code. You will use this code to obtain the authorization token needed to make the API requests.
To get your token, you will use the
requestAccessToken mutation as shown below.
Replace YOURID with your client ID, YOURSECRET with your client secret, and THE_AUTHORIZATION_CODE with the code you received as the
code parameter at the redirect URL. Once sent, you will receive a response like below.
Once you have your access token, you will use it as the Bearer Token when interacting with user-specific parts of our API, such as our Add Rating mutation.
Refreshing the Access Token
See the OAuth Refresh Guide page for instruction on using the
refresh_token to get new Access Tokens.