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)" \
The OAuth API will return a Bearer Token that expires in 3600s (1 Hour). The response is formatted as follows:
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"
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
The request is missing a required parameter, includes an unsupported parameter value (other than
unsupported_grant_type), or is otherwise malformed. For example,
refresh_token is not included.
Client authentication failed. For example, when the client includes
client_secret in the authorization header, but there's no such client with that
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
Client is not allowed for code grant flow or for refreshing tokens.
grant_type is anything other than
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.