Notice of V3 Schedule EPG API Upgrade

As part of critical security upgrades, Wurl has now released a v3 of the Schedule EPG APIs for all Partners. The v3 API utilizes a new OAuth token methodology for accessing channel EPG data, described in detail below.

All Wurl Partners must migrate to the v3 API by the end of September, 2022. Wurl will maintain the legacy v2 API for a short period of time after September, after which it will be deprecated.

Why are we doing this?

OAuth2 authentication is an industry-standard method that is more secure than basic authentication.
The use of access tokens that regularly expire limits security vulnerability without compromising the client’s EPG app credentials.
EPG access credentials are no longer stored by the Wurl Platform, allowing an added layer of protection in the unlikely event of a data breach.

Authentication Method Changes

Current Authentication Method

In the current v2 API, Partner authentication is handled by adding fixed EPG App UID and Secret appended directly to the Schedule EPG URL. The Partner's UID and Secret is added to the Base URL for each channel's Schedule data, as follows:

https://platform.wurl.com/api/schedule/<wurl_channel_slug>/schedule?appid=[REPLACE]&secret=[REPLACE]&date=<date>&num_days=<days>&format=<json or tivo>

New v3 Authentication Method

All Partners will be provided with a new EPG APP UID and Secret as part of the migration notification.

In the v3 API, Partners must first request an OAuth token from Wurl's OAuth API, using the Partner's EPG App UID and Secret. This token must then be added to the header of individual Channel EPG requests. See below for full details and examples.

Schedule API v3 Authentication Details & Examples

Follow the below steps and examples to utilize the new authentication method for Wurl Schedule EPG API v3.

1. Using your EPG App's unique UID & Secret, request a token from the Wurl OAuth API

Request an access token from the Wurl authentication provider https://auth.wurl.com/oauth2/token

Your EPG APP UID and Secret should be added to the request Headers, as follows:

curl 'https://auth.wurl.com/oauth2/token' \
-X POST \
-H "Authorization: Basic $(echo -n '<UID>:<SECRET>' | base64)" \
--data-urlencode 'grant_type=client_credentials'

The OAuth API will return a Bearer Token that expires in 3600s (1 Hour). The response is formatted as follows:

{"access_token":<token>,"expires_in":3600,"token_type":"Bearer"}

2. Pass the token in the header of your request to the Schedule API

Pass this OAuth token in the header of your request to access the Schedule EPG API data for all channels. The same token may be used to access all channel-specific Schedule APIs that are requested before the token expires.

curl 'https://platform.wurl.com/api/channels/<wurl_channel_slug>/schedule?format=<json or tivo>' \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

A properly formatted request will return the channel's Schedule EPG data in the format requested.

Rate Limits

When requesting Tokens, requests should not exceed 10 per second.

Example Error Response Types

If you run into an error code while following the above steps, please reference the below definitions for additional context to help better troubleshoot.

Sample error response

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
"error":"invalid_request|invalid_client|invalid_grant|unauthorized_client|unsupported_grant_type|"
}

Error Definitions

invalid_request

The request is missing a required parameter, includes an unsupported parameter value (other than unsupported_grant_type), or is otherwise malformed. For example, grant_type is refresh_token but refresh_token is not included.

invalid_client

Client authentication failed. For example, when the client includes client_id and client_secret in the authorization header, but there's no such client with that client_id and client_secret.

invalid_grant

Refresh token has been revoked.

Authorization code has been consumed already or does not exist.

App client doesn't have read access to all attributes in the requested scope. For example, your app requests the email scope and your app client can read the email attribute, but not email_verified.

unauthorized_client

Client is not allowed for code grant flow or for refreshing tokens.

unsupported_grant_type

Returned if grant_type is anything other than authorization_code or refresh_token or client_credentials.

Migration Timeline

Wurl is requesting that all Partners upgrade to the v3 API by September 30, 2022. During the period up until this date, Partners can continue to access the existing APIs. Once all partners have migrated to the v3 API, the v2 API will be deprecated.

Schedule EPG API V3: Upgrade Notification & Migration Process

browse