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, take the following initial steps:

1. Create 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. Activate Network and User – 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/...`

URLs

Users can generate tokens to access either their production or staging environments. Tokens must be used for the environment that they are generated for.

📘

Note

If the token and environment do not match (e.g. attempting to use a production token to access staging), the API will reject the request.

OAuth Token

Generate Access Token [POST /auth/token]

Generate an access token with a username/password or with client credentials. Tokens created with client credentials do not require a username/password to share.

Generate Token via password grant_type

Generate a token via MRM username/password authentication.

Example Request and Response

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'
 
# response
{"access_token":"_2qO9_xL4pSKrYfw_yWMH1tCWE4T45w5gKpnSYfWHgI","token_type":"Bearer","created_at":1694166080,"expires_in":604800}

Header Parameters

Request Body Parameters

Generate Token via client_credentials grant_type

Generate a token via client credentials. This method creates a token that does not require sharing usernames or passwords. To obtain client_id and client_secret from the MRM UI, see API Applications.

There are two ways to generate a token via client credentials.

Method 1. Set an Authorization header (requires HTTP basic authentication).

Example Request and Response

curl -X POST \
    'https://api.freewheel.tv/auth/token' \
    -H 'Authorization: Basic RkNJZXhhbXBsZTJnZW5lcmF0ZXRva2VuOmV4YW1wbGUyc2VjcmV0eHh4eXk=' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials'
 
# response
{"access_token":"h45z6CjW6cekxaKjGt6Xs9pnEg2Fgi1KEQikQR48iwM","token_type":"Bearer","created_at":1694078736,"expires_in":282203}

Method 2. Insert client_id and client_secret in the request body.

Example Request and Response

curl -X POST \
    'https://api.freewheel.tv/auth/token' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'client_id=FCIexample3generatetoken' \
    --data-urlencode 'client_secret=example3secretxxxyy'
 
# response
{"access_token":"h45z6CjW6cekxaKjGt6Xs9pnEg2Fgi1KEQikQR48iwM","token_type":"Bearer","created_at":1694078736,"expires_in":280995}

Header Parameters

Request Body Parameters

Response Attributes

These attributes are supplied in the body of the response.

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

Retrieve an OAuth token's info.

Example Request and Response

curl -X GET \
    'https://api.freewheel.tv/auth/token/info' \
    -H 'Authorization: Bearer 12qO9xxL4pSKrYfw_yWMH1tCWE4T49w5gKpnSYfWHgI'
 
# response if the token was generated by password grant_type
{"user_id":32760,"expires_in":367327,"created_at":1694166080}
 
# response if the token was generated by client_credentials grant_type
{"client_id":"FCIexample4retrievetokeninfo","expires_in":280207,"created_at":1694078736}

Header Parameters

Response Attributes

These attributes are supplied in the body of the response.

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

Revoke an access token.

Example Request and Response

curl -X POST \
    'https://api.freewheel.tv/auth/token/revoke' \
    -H 'Authorization: Bearer h45z6CjW6cekxaKjGt6Xs7pnEg2Fgi1KEQikQR48iwM' \
    --data-urlencode 'token=h45z6CjW6cekxaKjGt6Xs7pnEg2Fgi1KEQikQR48iwM'
 
# response if the token was generated by password grant_type
{"user_id":32760,"expires_in":366226,"created_at":1694166080}
 
# response if the token was generated by client_credentials grant_type
{"client_id":"FCIexample5revokeaccesstoken","expires_in":278835,"created_at":1694078736}

Header Parameters

Request Body Parameters

Response Attributes

These attributes are supplied in the body of the response.