Introduction

FreeWheel's OAuth 2.0 service provides a centralized and unified authentication mechanism for accessing FreeWheel APIs, including all versions of Streaming Hub APIs (V1–V4) and Instant Video Ingest (IVI).

Clients authenticate with the OAuth service to obtain a Bearer access token, which is then included in API requests using the Authorization header. This token enables secure access to protected API resources across FreeWheel services.

FreeWheel supports both user-based and application-based authentication methods:

• Application credentials (Recommended): Tokens are generated using application credentials (client_id and client_secret) for secure, server-to-server integrations.
• User credentials: Existing integrations may continue to use username/password flows; however, this approach is being phased out in favor of application-based authentication.

Token lifetimes vary depending on the authentication method and application type (see below for current guidance).

📘

NOTE

Bearer tokens are case sensitive.

The OAuth 2.0 service also supports revoking and regenerating access tokens at any time prior to expiration. The access token returned via the OAuth service is functionally equivalent to the Streaming Hub User API token.

To protect the authentication service, token generation endpoints are rate-limited. For example, token requests are limited to 3 requests per second per IP address. Requests exceeding this threshold may be throttled and return an HTTP 429 response.

Getting Started

To get started with FreeWheel APIs, use API Management in Streaming Hub to create and manage applications and credentials.

1. Access API Management: Streaming Hub Admin users can access the API Management page in the Admin Center.
2. Create an Application: Create a new application based on your use case:
   1. Internal Developer (for internal integrations)
   2. External Partner Developer (for third-party integrations)
3. Configure Permissions: Select the API permissions required for your application directly within API Management.
4. Generate Credentials: Once configured, generate your application’s credentials (e.g., client_id and client_secret) for authentication.
5. Access Additional APIs: Most API access can be enabled directly within API Management.
   For any APIs not available in this experience, contact your account team or open a support ticket via email at [email protected] or via the support portal (which requires Zendesk access.)

For more information, see API Management in Streaming Hub.

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 in the environment 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 Streaming Hub 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 an access token using the client credentials flow. This method authenticates using application credentials (client_id and client_secret) and does not require sharing usernames or passwords.

To obtain your client_id and client_secret, see API Management in Streaming Hub.

Authentication is performed using standard HTTP Basic authentication by including your credentials in the Authorization header.

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.

Recommended Token Usage

• Reuse the access token for API requests until it expires
• Do not request a new token for every call
• When the token expires, the API will return 401 Unauthorized
• Upon receiving a 401, obtain a new access token

This approach reduces unnecessary authentication calls and aligns with modern token-based authentication practices, where expiration is enforced directly by the API.

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

Deprecation Notice: Retrieve Token Info

The GET /auth/token/info endpoint:

• Is not available for applications created via API Management
• Will be phased out for all applications in a future release

Migration Guidance

Clients should:

• Stop calling /auth/token/info to validate tokens
• Use the access token until it expires
• Handle expiration via 401 Unauthorized responses
• Request a new token when needed: Request a new access token or use refresh token

Access tokens should be treated as temporary credentials and refreshed as needed rather than validated before each request.

Deprecated - 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}

Deprecated - Header Parameters

Deprecated - 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 for tokens not created via API Management.