Introduction

FreeWheel's OAuth 2.0 Service provides a centralized and unified authentication mechanism to access FreeWheel's API services. These include all versions of MRM APIs (V1-V4) and Instant Video Ingest (IVI).

The OAuth 2.0 service accepts standard MRM User Login credentials (username/password), and returns an API bearer token with a lifetime of 7 days (168 hours).

📘

Bearer tokens are case sensitive.

The OAuth 2.0 service also permits revoking and regenerating the user’s access token at any time prior to the 7-day lifetime. The access token returned via the OAuth service is identical in functionality to the current MRM User API token.

Because the token is valid for 7 days, this endpoint is rate-limited to 3 requests per second per IP address. Any HTTP requests beyond the 3 requests in a one-second time window will be throttled and return an HTTP 429 error.

Getting Started

To get started with OAuth 2.0, the following initial steps need to be taken:

1. Creation of an MRM User – Any MRM User Login may be used. If you do not have one allotted for your API interface, one can be created for you by your MRM system administrator as any standard MRM User.
2. Network/User Activation – While you can generate an OAuth token, FreeWheel's Open APIs will reject any requests until the network and user are authorized. This must be configured by FreeWheel for any MRM user. Please contact your FreeWheel Account Team for this initial step. It only needs to take place once for an entire network and for each MRM user that needs access.

📘

Note

If you want to know which APIs you have access to, contact your account team or open a support ticket via email at [email protected] or via the support portal (which requires Zendesk access.)

Using the OAuth Service

These APIs provide methods to generate, verify, and revoke an access token using either XML or JSON. If unspecified, the default response will return in JSON.

FreeWheel uses the OAuth 2.0 standard (RFC 6749). You can find more information about the Resource Owner Password Credentials Grant (ROPCG) workflow in the specification.

Once you have a valid access token, you can authenticate yourself at FreeWheel APIs by using the header "Authorization: Bearer [your_access_token]". For example:

curl -X GET
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer MY_OAUTH_ACCESS_TOKEN' \
  `https://api.freewheel.tv/services/...`

Data Structures

TokenData

• access_token: DAEhfruA7rl6rWdrdjImUOWzSqhwku1AhMwpXTUhunXA -The token to be used when authenticating against FW's APIs
• token_type: Bearer -The type of token in the workflow|Will always be "Bearer" for ROPCG
• created_at: 1468982119 (number) -The timestamp indicating when the token was created
• expires_in: 604800 (number) -The time remaining until the token expires, relative to the time the response was generated

TokenInfoData

• user_id: 6092302 (number) -User id
• expires_in: 604800 (number) -The time remaining until the token expires, relative to the time the response was generated
• created_at: 1468982119(number) -The timestamp indicating when the token was created

OAuth Token

Response Attributes

These attributes be supplied in the body of response.

Generate Access Token [POST /auth/token]

Generate an access token

Example

curl -X POST \
  https://api.freewheel.tv/auth/token \
  -H 'accept: application/json' \
  -H 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=password' \
  --data-urlencode 'username=johndoe' \
  --data-urlencode 'password=A3ddj3w'

Parameters

Request JSON

Headers

Content-Type: application/x-www-form-urlencoded
Accept: application/json

Body

grant_type=password&username=johndoe&password=A3ddj3w

Response 200 (application/json)

Attributes(TokenData)

Request XML

Headers

Content-Type: application/x-www-form-urlencoded
Accept: application/xml

Body

grant_type=password&username=johndoe&password=A3ddj3w

Response 200 (application/json)

Body

<oauth>
  <access_token>DEhfruA7rl6rWdrdjImUOWzSqhwku1AhMwpXTUhunXA</access_token>
  <token_type>Bearer</token_type>
  <created_at>1470063090</created_at>
  <expires_in>604800</expires_in>
</oauth>

Retrieve Token Info [GET /auth/token/info]

Retrieve an OAuth token info

Example

curl -X GET \
  https://api.freewheel.tv/auth/token/info \
  -H 'accept: application/json' \
  -H 'authorization: Bearer MY_OAUTH_ACCESS_TOKEN'

Request JSON

Headers

Accept: application/json
Authorization: Bearer MY_OAUTH_ACCESS_TOKEN

Response 200 (application/json)

Attributes(TokenInfoData)

Request XML

Headers

Accept: application/xml
Authorization: Bearer MY_OAUTH_ACCESS_TOKEN

Response 200 (application/json)

Body

<oauth>
  <user_id>6092302</user_id>
  <expires_in>604800</expires_in>
  <created_at>1468982119</created_at>
</oauth>

Revoke Access Token [POST /auth/token/revoke]

Revoke an access token

Example

curl -X POST \
  https://api.freewheel.tv/auth/token/revoke \
  -H 'authorization: Bearer MY_OAUTH_ACCESS_TOKEN' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'token=MY_OAUTH_ACCESS_TOKEN'

Request

Authorization: Bearer MY_OAUTH_ACCESS_TOKEN
Content-Type: application/x-www-form-urlencoded

Body

token=MY_OAUTH_ACCESS_TOKEN

Response 200