Setting Up User Oauth

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:

https://www.podchaser.com/do-auth?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URL&scope=SCOPES

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.

POST https://api.podchaser.com/graphql

mutation {
    requestAccessToken(
        input: {
            grant_type: AUTHORIZATION_CODE
            client_id: "YOURID"
            client_secret: "YOURSECRET"
            redirect_uri: "https://podchaser.com",
            code: "THE_AUTHORIZATION_CODE"
        }
    ) {
        access_token
        refresh_token
        token_type
    }
}

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.

Example Response

{
    "data": {
        "requestAccessToken": {
            "access_token": "YOURACCESSTOKEN",
            "refresh_token": "YOURREFRESHTOKEN",
            "token_type": "Bearer"
        }
    }
}

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.

Setting Up Your Redirect URL​

Identify Which Scopes You Need​

Send User to OAuth Page​

Handling Authorization Code​

Example Response​