API Authentication with OAuth 2.0

Authentication for third-party applications for use of the API methods provided by Blubrry.com.


Getting Started

The Blubrry API uses the OAuth 2.0 protocol for authentication and authorization. Blubrry supports common OAuth 2.0 scenarios such as those for a web server, installed and client-side applications.

To begin, obtain OAuth 2.0 client credentials by requesting them from the Blubrry Contact Form. After client credentials have been received, your client application can request an access token from the Blubrry Authorization Server, extract a token from the response and send the token to the Blubrry API that you want to access.

The two endpoint URLs that an application using OAuth2 may need are as follows:
  • Authorization Endpoint: https://api.blubrry.com/oauth2/authorize
  • Token Endpoint: https://api.blubrry.com/oauth2/token

While using OAuth2, your application must also supply its own redirect URI to return authorization codes and access tokens back to your application. Connections made to Blubrry must use HTTPS. Examples below use the cURL command line tool, but your application may use your HTTP client of choice.

The uses of both endpoints are further explained in the Summary section of this page.

For more documentation on the use of OAuth2, see the resources below. Note: Resources below are for reference only and cover all different types of OAuth2 authentication methods, which may not be supported by Blubrry.


Authenticating

Blubrry.com allows four OAuth2 grant types:

  • authorization code
  • implicit
  • refresh token
  • user credentials

Each grant type has its own purpose.

The authorization code and implicit grant types both redirect users to the authorization endpoint listed above in the Getting Started section. HTTPS GET information is appended to the authorization endpoint to request an authorization code or access token and then return the user to the redirect URI. refresh token and user credentials grand types allow an application to work directly without any user interaction in the process. Due to security reasons, the user credentials method is only available by request and is only granted upon approval.

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. First, redirect the user to the following URL after replacing “ClientID” with the actual client ID, “https://example.com/something” with the actual redirect URL/URI, and random with your 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. A successful authorization will pass the client the authorization code to the supplied redirect URL via HTTPS

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

    Note: For a web server, the script something would confirm the GET parameter state matches the state value they supplied in step 1 and if valid, use the code value in step 3.  The file name, extension or scripting language is not relevant. In a mobile application, the /something path may not be relevant.

  3. Within 5 minutes of the user authenticating, an access and refresh token can be requested via HTTPS client within your application or website. The example below uses cURL, using the received authorization code and redirect_uri values.

    $curl -u ClientID:ClientSecret https://api.blubrry.com/oauth2/token -d ‘grant_type=authorization_code&code=d2d20edf0ec39416fd948cd99169c0502d740e38&redirect_uri=https://example.com/something 

  4. A token will be returned in JSON format, similar to the one 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 refresh token does not expire. Storing refresh tokens as well as your client secret encrypted is required. If the refresh tokens cannot be stored securely, your application should use the implicit grant type.

The access token that is returned will expire after one hour. You may proceed to use this token for 1 hour and upon its expiration, use the Refresh Token method noted below to receive a new access tokens.

Implicit

The implicit grant type is used to request access to protected resources on behalf of a third party.

The implicit grant type is typically used for public clients such as those implemented in javascript or on devices where client credentials cannot be stored securely.

  1. First, redirect the user to the following URL after replacing “ClientID” and “https://example.com/something” with the actual client ID and redirect URI:

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

  2. A successful token request will be returned in the fragment of the URL.

    https://example.com/something#access_token=3b636a92ee50a8f17543f6a531b27e55d525bcd1&state=random&token_type=bearer&expires_in=3600

The implicit grant type will not return a refresh token and the access token that is returned will expire after one hour.

Refresh Token

Access tokens have limited lifetimes. If your application needs access to the Blubrry API beyond the lifetime of a single access token, it can obtain a refresh token. A refresh token allows your application to obtain new access tokens.

Make sure to save refresh tokens in secure long-term storage and continue to use them, as they do not expire.

  1. Once a refresh token is obtained, it can be used to generate a new access token: $ curl -u ClientID:ClientSecret https://api.blubrry.com/oauth2/token -d ‘grant_type=refresh_token&refresh_token=55b01e60a74e45b3c66032627dcbc0dddd0bbd6a
  2. A token will be returned in JSON format, similar to the one below, or else an error message will be returned in JSON format. {“access_token”:”290fd91574ae4cc510c5496549bfbc337bf9cce5″, “expires_in”:3600, “token_type”:”bearer”, “scope”:null}

The access token that is returned will expire after one hour.

User Credentials

The user credentials “password” grant type is used to request access when having the clients user name and password. Note, this method is not available by default, you must contact Blubrry with an explanation why such access is required. In most cases, the Authorization Code method is more than likely the authentication method you should use.

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. Because of the security risks associated with sharing account passwords with 3rd parties, this method is not available by default.

  1. First, make a request to the following URL with your client ID, client_secret, username, and password.

    https://api.blubrry.com/oauth2/authorize?grant_type=password&client_id=CLIENT_ID&client_secret=SECRET&username=EMAIL&password=PASSWORD

  2. A token will be returned in JSON format, similar to the one below, or else an error message will be returned in JSON format.

    {“access_token”:”3b636a92ee50a8f17543f6a531b27e55d525bcd1″, “expires_in”:3600, “token_type”:”bearer”, “scope”:null, “refresh_token”:”55b01e60a74e45b3c66032627dcbc0dddd0bbd6a”}

Please contact Blubrry support for more information regarding authentication via user credentials.

After Authenticating

After authentication with the server, the application will be able use an HTTP client client of choice (or cURL from the command line for testing) access all of Blubrry’s API methods with active access tokens. API methods will return JSON encoded results containing the information requested.

The following cURL example shows how to uses an access token to retrieve the list of programs (List Programs API function call) under the account tied to the access token.

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