Introduction

All Radio Workflow API's use OAuth2 specifications to authenticate a request. You should, if not already, become familair with this. Authorization is received by performing the "Authorization Code" version of authorization as specified in section 4.1 of RFC 6749. This will issue you a short-lived, single-use code that you will be able to exchange for an access_token and refresh_token for the Instance.

📘

What is an Instance?

Our customers data is in an isolated instance, which means that one of our customers cannot access and see another customers data. For example, Desert Broadcasters is only able to see Desert Broadcasters, your access_token granted by Desert Broadcasters can only view data in their instance.

Requests to the token and the refreshToken endpoints do not require an access_token, but they both require a Basic Authorization header containing your PartnerKey as well as your PartnerSecret. Refer to Client side here for more information on how to construct a Basic Authorization header.

❗️

Keep your Partner Secret secure

We will never require and you should ensure you never expose your Partner Secret in any query paramaters, doing so is a security risk.

Step 1

Construct and redirect your users to the authorize endpoint, the user will then grant you the required scopes to be able to interface with our API's.

🚧

The constructed URL should look like this

https://www.radioworkflow.com/app/listeners/authorize?response_type=code&client_id=[PARTNER_KEY]&state=[TRACKING_ID]&scope=basic.

You can request multiple scopes by supplying a space-delimited (but url-safe) list of scopes in your authorize request. It will look like this: &scope=basic%20dubbed

Step 2

Once the user has granted your access to their Radio Workflow instance, they will be redirected to your Partner Redirect URI. You will be able to access a new authorization code in the query parameters of the request.

👍

We redirect the user back to your website

http://www.your-app-url.com/?code=[AUTHORIZATION_CODE]&state=[TRACKING_ID]

Step 3

Now that you have your authorization code, you can exchange it for an access_token by making a request to the token endpoint. When you receive your access_token, you will also be given a refresh_token as well. Be aware, your access_token is short lived, whereas your refresh_token lives longer and can be used in exchange of a new access_token.

{
  "access_token": "a07955c33f2f59f247381a816b01f976871cb388",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "basic",
  "refresh_token": "cc7e1b41902715b3316830679c64238c8bafb40f"
}

👍

Other Grant Types

We have further authentication options available for trusted Partners and where the below authentication flow doesn't fit in well with your application. To become a trusted Partner, you must go through a review process with us to ensure that our customers data is protected.