OAuth 2

Using OAuth 2 for accessing the Blubrry API

Getting Started

  1. Request API credentials using the Blubrry contact form.
  2. Generate an access token using one of the methods outlined below.
  3. Use the access token to make API calls to Blubrry’s API
  4. Use the refresh token to get new access tokens for future calls

Blubrry supports two possible flows that an application can use to obtain access: Authorization Code grant and User Credentials grant.

Authorization Code

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. 

  4. Use the refresh token 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

User Credentials

The user credentials password grant type is used to request access when having the client user name and password.  The user credentials password grant type is typically used for internal company applications where user names and passwords are managed securely. The security of the accounts in this case is passed onto the application developers.

Due to the security implications associated with sharing account passwords with 3rd parties, this method is not available by default and must be requested from Blubrry with an explanation of the use case. The User credentials method is limited to the account that the client ID and secret are associated with. In most situations, the Authorization Code method should be the authentication method of choice.

    1. Make a request to the following endpoint using your client ID, client secret, username and password:
        
      curl -X "POST" "https://api.blubrry.com/oauth2/authorize"     
           -H "Authorization: Basic base64-of-clent-id-colon-client-secret"  
           -d grant_type=password
           -d username=USERNAME
           -d password=PASSWORD

      A token will be returned in JSON format as shown below:
      {
         "access_token":"3b636a92ee50a8f17543f6a531b27e55d525bcd1", 
         "expires_in":3600, “token_type”:”bearer", 
         "scope”:null, 
         "refresh_token":"55b01e60a74e45b3c66032627dcbc0dddd0bbd6a"
      }

 

  1. Use the refresh token 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 after Authentication

After authentication with the server, the application will be able use the access token generated by one of the methods above along with cURL or an HTTP client client of choice 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"