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

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.

Production
https://api.freewheel.tv/auth/token
Staging
https://api.stg.freewheel.tv/auth/token

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

NameValueRequired?
Content-Typeapplication/x-www-form-urlencodedYes
Acceptapplication/xml or application/jsonNo. If not set, default response is json

Request Body Parameters

NameTypeRequired?Description
grant_typestringYesValue must be password
usernamestringYesUsername of user
passwordstringYesPassword of user

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

NameValueRequired?
Content-Typeapplication/x-www-form-urlencodedYes
Acceptapplication/xml or application/jsonNo. If not set, default response is json
AuthorizationBasic base64-client_id-client_secretRequired if client_id and client_secret not set in request body

Request Body Parameters

NameTypeRequired?
grant_typestringValue must be client_credentials
client_idstringRequired if Authorizationheader not set
client_secretstringRequired if Authorizationheader not set

Response Attributes

These attributes are supplied in the body of the response.

Response ItemDescriptionComments
access_tokenThe generated token. Used when authenticating against FreeWheel'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

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

NameValueRequired?
Acceptapplication/xml or application/jsonNo. If not set, default response is json
AuthorizationBearer MY_OAUTH_ACCESS_TOKENYes

Response Attributes

These attributes are supplied in the body of the response.

Response ItemTypeDescription
client_idstringThe client_id that generated the token. Only exists if the token was generated by the client_credentials grant_type
user_idnumberThe id of the user that generated the token. Only exists if the token was generated by the password grant_type
created_atnumberThe timestamp indicating when the token was created. Given in Unix time (a.k.a. POSIX or Epoch time)
expires_innumberThe time remaining until the token expires, relative to the time the response was generated. Given in seconds, maximum length is 7 days

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

NameValueRequired?
Content-Typeapplication/x-www-form-urlencodedYes
Acceptapplication/xml or application/jsonNo. If not set, default response is json
AuthorizationBasic base64-client_id-client_secretYes

Request Body Parameters

NameTypeRequired?Description
tokenstringYesThe access token to revoke

Response Attributes

These attributes are supplied in the body of the response.

Response ItemTypeDescription
client_idstringThe client_id that generated the token. Only exists if the token was generated by the client_credentials grant_type
user_idnumberThe id of the user that generated the token. Only exists if the token was generated by the password grant_type
created_atnumberThe timestamp indicating when the token was created. Given in Unix time (a.k.a. POSIX or Epoch time)
expires_innumberThe time remaining until the token expires, relative to the time the response was generated. Given in seconds, maximum length is 7 days