FreeWheel's Publisher API Documentation Platform

Welcome to FreeWheel's Publisher API documentation. You'll find comprehensive getting-started guides, introductory pages for each API, and endpoint documentation to help you start working with FreeWheel Publisher APIs as quickly as possible. You can also take advantage of the Run in Postman button on each endpoint page to test the API methods.

Use the links below to view the API documents in this platform.

Getting Started    API Reference

Getting Started with Authentication

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).

Today, users can manually retrieve API Tokens from their profile page in the MRM UI, which can then be handed to developers for coding into the customer’s web services. OAuth replaces this deprecated process with a web service for those customer systems to retrieve directly. The UI-generated API Tokens will be removed in January 2018.

The OAuth 2.0 service accepts standard MRM User Login credentials (username/password), and returns an API token with a lifetime of 7 days (168 hours). The 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.

Note: The MRM User API Token collected from a user’s Profile page will no longer function from January 17, 2018 onward. Thereafter, the OAuth 2.0 service will be the only method for API Token retrieval.

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.

ParameterDescriptionComments
access_tokenThe token to be used when authenticating against FW's APIs
token_typeThe type of token in the workflowWill always be "Bearer" for ROPCG
created_atThe timestamp indicating when the token was createdGiven in Unix time (a.k.a. POSIX or Epoch time)
expires_inThe time remaining until the token expires, relative to the time the response was generatedGiven in seconds, currently max is 7 days

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' \
  -d 'grant_type=password&username=johndoe&password=A3ddj3w'

Parameters

NameTypeDescription
grant_typestringRequired. grant_type only allow password
usernamestringRequired. username of user
passwordstringRequired. password of user

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

Updated about a year ago



Getting Started with Authentication


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.