Using OAuth 2 for accessing the Blubrry API

The blubrry API is available to customers to manage aspects of their podcast production and includes publishing episodes, uploading media files, and retrieving podcast statistics. Blubrry also includes a Network API specifically for Professional customers who want to provide a podcast network on their own WordPress website.

Getting started with OAuth 2 for accessing the Blubrry API

  1. Request API credentials by signing into your Blubrry account. Once signed in select “Manage Account” from the account menu at the top right. From the Manage Account page,  select Create API Key under the “Developers” section.
  2. Generate an Access and Refresh token using one of the Authorization Code Flow outlined below.
  3. Use the Access token within a 1 hour window to make API calls to Blubrry’s API
  4. Use the Refresh token API call to get new access token at a later date and time.

Note the Refresh token does not expire and is specific to the account authorized during the Authorization Code process.

Applications must store the access and refresh tokens using a secure mechanism. 

Authorization Code Flow

The Authorization Code grant type is used when the client wants to request access to protected resources on behalf of another user (i.e. a third party). This is the grant type most often associated with OAuth. The authorization code grant type is typically used for web applications or mobile applications where a client’s secret can be stored securely.

  1. Send the user to the following URL using your client ID, redirect_uri and random state value.

    https://api.blubrry.com/oauth2/authorize?response_type=code&client_id=ClientID&redirect_uri=https%3A%2F%2Fexample.com%2Fsomething&state=random

    Note: This is not an API call from your server to our servers. This URL is placed into a web browser typically as a clickable link in a web page or via a HTTP 302 “Location: URL” redirect. Mobile applications typically use a web browser control and load the URL directly in order to invoke the sign in page within their app and provide a customized return URL their application will intercept. Mobile applications typically use a custom redirect_uri value with a custom schema (myapp:// instead of https://). 

  2. Upon successful authorization, Blubrry sends them back to your application’s redirect_uri  along with an authorization code:

    https://example.com/something?state=random&code=d2d20edf0ec39416fd948cd99169c0502d740e38

    Once your application confirms that the GET parameter state returned matches the state value you supplied in step 1,  it can then use the code value in the next step. Note: The authorization code can only be used once and expires after 5 minutes.

  3. Use the authorization code obtained in the previous step to request an access token and a refresh token from the Blubrry OAuth2 token endpoint: 
    curl "https://api.blubrry.com/oauth2/token" \ 
-u clientId:clientSecret \ 
-d grant_type=authorization_code \
-d code=d2d20edf0ec39416fd948cd99169c0502d740e38 \
-d redirect_uri="https://example.com/something"
    A token will be returned in JSON format as shown below. In the event of an error, an error message will be returned in JSON format. 
    { 
     "access_token":"3b636a92ee50a8f17543f6a531b27e55d525bcd1", 
     "expires_in":3600, "token_type":"bearer", 
     "scope":null, 
     "refresh_token":"55b01e60a74e45b3c66032627dcbc0dddd0bbd6a" 
}
    The access token returned will expire after one hour, or if a new access token is issued. You can use this token for up to one hour, after which you will have to use the refresh token to get a new access token. 

    Note: the refresh token does not expire and is used to obtain access tokens when API access is necessary at any time into the future. Refresh tokens however can be revoked for security purposes either by the account holder or by Blubrry for security reasons. Anytime the refresh token is revoked, the “Authorization Code” method must be re-used to obtain a new refresh token.

  4. Use the Refresh token API call to obtain a new access token 
    curl "https://api.blubrry.com/oauth2/token" 
     -u clientId:clientSecret 
     -d grant_type=refresh_token 
     -d refresh_token=55b01e60a74e45b3c66032627dcbc0dddd0bbd6a

Making an API Call with an Access Token

The application will be able use the access token for up to 1 hour to access all of Blubrry’s API methods. API methods will return JSON encoded results containing the information requested. The example below shows how to use an access token to retrieve the list of programs under the account tied to the access token by making a call to the List Programs API .  

curl -H "Authorization: Bearer 3b636a92ee50a8f17543f6a531b27e55d525bcd1"  "https://api.blubrry.com/2/media/index.json"

Making an API after the Access Token expired

Access tokens expire after 1 hour of their issuance. To obtain a new one,  the Refresh token API call is used to obtain a new access token. Blubrry Refresh tokens do not expire and allow your application to persistently maintain access to the API for indefinite periods of time.  Please see step 4 in the Authorization Code Flow section for an example how to use the Refresh token API call.

Why does the access token expire after 1 hour?

Access tokens provide direct access to the Blubrry API without providing any other information. Because the access token has access to the API representing that Blubrry account without requiring any other authentication such as the account’s credentials or the application’s key or secret, it is critical that the window of time this access token works is minimal. The industry standard today is to use a 1 hour window.

You can think of the access token as a hotel door key that only works for 1 hour. If after an hour passes the key card expires requiring you to return to the hotel’s service desk to confirm your identity. Think of your hotel reservation as your refresh token and your passport or government ID as your application key and secret.  Presenting your reservation number along with your ID allows you to get your hotel key card re-validated for another hour.

When the access token expires, you will obtain a new access token by using the refresh token API call.   The refresh token, application’s key and secret are then used to obtain a new access token. The access token short expiration forces applications to refresh often giving the API a chance to revoke an application’s access for a variety of reasons such as when the Blubrry account was deleted or if the application’s key and secret were compromised.