Authorization

caution

The regular access tokens should not be used in any environment where they could be exposed to the end user. If compromised, you should contact Podchaser to revoke the access token. To access the API from a client application, use a Limited Scope token as described at the bottom of this page.

The API uses OAuth 2 to authenticate and authorize clients. Within your API settings, you will have keys for a Development Client and Production Client.

At this time, both work the same way and use the same environments. However, it is recommended to use the development keys while developing new integrations or updating existing integrations. In the event your keys get compromised due to committing to a repo, you could then easily regenerate your development keys without affecting your production code if it uses the production keys.

Before you can make any queries, you will need to get your access token. You will then use this access token as a bearer token in an authorization header for all queries and mutations.

Note: If you are needing to authenticate users to make actions within the API, such as leaving reviews or ratings, you will want to follow our User Oauth guide as that process is a little different than below.

Getting Your Access Token

To get your access token for your development or production keys, use the requestAccessToken mutation within the API itself.

The access tokens last 1 year so you should store this token so you do not need to request new tokens with each query.

Using the API

To get your token, you will use the requestAccessToken mutation as shown below. The "client_id" will be your API Key and the "client_secret" will be your API secret.

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

mutation {
    requestAccessToken(
        input: {
            grant_type: CLIENT_CREDENTIALS
            client_id: "YOURAPIKEY"
            client_secret: "YOURAPISECRET"
        }
    ) {
        access_token
        token_type    # Optional, will always be "Bearer"
        expires_in    # Optional, will always be 31536000
    }
}

Example Response

{
    "data": {
        "requestAccessToken": {
            "access_token": "YOURACCESSTOKEN",
            "token_type": "Bearer",
            "expires_in": 31536000
        }
    }
}

Be sure to save the access_token field somewhere so you can use it on all your future queries.

Using Your Access Token

Once you have your access token, you will use that token as an authorization bearer token in all of your queries. For example, if you are fetching a specific podcast, you would make a POST request to our API with the Authorization header set to "Bearer YOURACCESSTOKEN" as shown in the example below.

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

Authorization: Bearer YOURACCESSTOKEN

query {
    podcast(identifier: {id: "731600", type: PODCHASER}) {
        title,
        description,
        applePodcastsId
    }
}

Limited Scope Client Credentials Token​

Your app can request an access token with limited scope that is safe to use directly from your mobile app or client application. These tokens will only allow read access to common entities, and will expire in an hour to limit their usage if compromised. Set the limited_scope to true when requesting an access token to retreive one.