Media portal is the portal for Lumen® CDN and Lumen® Vyvx® services. Through Media portal, you can configure user accounts, group your services for reporting purposes, view historical and real-time usage, and order and configure new services.
Lumen web-service APIs (application programming interfaces) allow developers to build software that interacts directly with the Lumen CDN portal data without requiring use of the browser-based user interface. While the browser-based portal is ideal for many users, some situations require access to data feeds so that customers may incorporate Lumen CDN data directly into their own tools and systems. Media portal APIs are designed to meet this need.
Over time, we aim to provide APIs for each functional area available in Media portal.
The authentication, authorization and API style is common across the full product set. (For example, Caching APIs and Streaming APIs use a similar style, without requiring a different set of credentials to access them.)
The API interface style used is representational state transfer (REST). The hierarchical organization of the CDN service tree makes the REST style a good fit for the CDN APIs. The service tree hierarchy for the purposes of calling the APIs is: Access Group > SCID > Network Identifier.
The API architecture is stateless.
The default host for all API calls is: https://ws.lumen.com
The APIs described in this section belong to Media portal API version 1.5 by default. As APIs in version 2.0 are created, their descriptions will be added, and version numbers will be noted.
Media portal APIs follow the REST (representational state transfer) style. RESTful web services leverage the design principles of HTTP 1.1.
The common HTTP methods are used to denote the nature of the action to be taken—the “verb”. (For example, the GET method is used only to retrieve data, never to delete it.) The URI contains the information that defines what the call acts upon—the “nouns”. URIs are constructed logically, reflecting natural hierarchies of resources and are designed to be easily human-readable.
APIs are called by making an HTTP request with a selected method to the required URI. Responses include XML data in the request response body providing the requested data or result of the operation. Each request must be signed in order to be authenticated by the process.
Follow these steps to prepare to use Media portal APIs:
This topic is intended for developers who use API keys to create the API signature. Use the information in the API descriptions topics and examples from the API sample code to build your request.
Learn more about creating API security keys
A Media portal API key is a numeric ID that is used in conjunction with an alphanumeric secret. These two parts are used to construct a request signature to authenticate Media portal API requests.
An API key has the following characteristics:
It is best practice to disable keys when they are not currently being used. Failure to disable a key could result in unauthorized access to your CDN service information and configuration.
If you believe that a third-party has gained knowledge of your API key secret, you should generate a new one immediately.
Each API key is assigned to a (single) role when the key is created. Roles contain permissions that determine access to features within Media portal.
As with users, API keys inherit authorizations from parent to child access groups down the hierarchy. Conversely, keys created in a child access group do not have authorization for actions in a higher-level, parent access group.
Media portal uses access groups to control the scope of services and network identifiers (properties, streaming IDs, and vhosts) accessible to any portal user. Access group security rules govern what a user can do to services/network identifiers if they have access.
The number of API keys is limited. Authorized users can generate up to five API keys per access group.
An API key can have one of the following statuses:
||Key has not been used in 180 days or more. (For more information, see: API Security Key Deactivation Policy.)|
|Disabled||The key is valid, but requests from this key are rejected.
If the key has been disabled by an admin in a parent access group, the Enable Key function is not active in child access groups.
You can view the status of any key in Media portal.
An administrator who disables a key can enable that same key within their access group. However, they cannot take those actions on keys disabled by an admin of a parent access group if they have not been assigned to the group.
Media portal limits the rate and number of requests per API key per minute. The current rate limit is 25 per minute.
If the rate of requests is higher than the defined rate, further requests are denied until a subsequent time period begins. Requests over the rate amount create a log event.
Rate limits are enforced after the request is authenticated.
If necessary, you can disable a single API key. All requests using a key in Disabled status are rejected. (Learn more about enabling or disabling an API security key.)
Disabled API keys can be enabled by the same administrator, by a peer administrator, or by an administrator associated with a parent access group.
Whenever Media portal receives an API request, it follows this process:
If the request is rejected for one of the above reasons, Media portal returns an HTTP status code:
|Description||Response code||Entity body returned to client|
|Authentication failure||403||None. No entity body is returned to the caller to limit exposing data to a potentially malicious request.|
|Request timestamp is too old||403||mpeRequestTooOld|
|API key is disabled||403||mpeAPIKeyDisabled|
|Access group API privileges suspended||403||mpeAPIPrivilegesSuspended|
|API key request rate too high
After you have the API key and secret, you can locate the access group ID, which is used to develop your API request. Each API request requires the access group ID as part of the scope.
To determine the access group ID:
<apikey id="14816" xsi:noNamespaceSchemaLocation="https://ws.level3.com//schema/keyv1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<assignedAccessGroup id="1" name="Level3 Internal"/>
<contact id="12345" name="firstname.lastname@example.org"/>
<role id="5" name="Admin"/>
In order to protect access to your CDN services, Media portal APIs include a robust security mechanism. In addition to using HTTPS to ensure that requests and response contents are encrypted, every request presented to the API web services must be “signed”. A valid signature confirms that the request has been sent by an authenticated API key.
API authentication is bi-directional between Lumen and the requestor.
Once the request is authenticated, the API key's authorization level is evaluated using the assigned role and rate limits.
The signature mechanism used by Media portal APIs is HMAC (hash-based message authentication code) and the SHA-1 cryptographic hash function.
The process works as follows:
The authorization HTTP request header field expected from clients is:
MPA [API Key ID]:[signature]
MPA (Media Portal Authentication) is the authentication scheme and signature is a value that is properly constructed as described below.
If an accept header is set in the request, the only valid value is text/XML. Any other value will receive a 406 response.
This signature is constructed in the form of a RFC2104 HMAC-SHA1 digest. Create a string as follows:
[Date ] + “\n” + [RelativePath] + “\n” + [Content-Type] + "\n" + [HTTP-Verb] + “\n” + [Content-MD5]
Encode this string as UTF8, construct an HMAC-SHA1 digest (using the secret), then encode the result in Base64. The output of these steps is the signature. (For implementation examples, see sample code.)
Unauthenticated requests are rejected and an HTTP status is sent. Unauthenticated requests include:
If a request fails authorization, Media portal sends a response code to the requester and logs the request (IP address, requested URI, key ID, date and time). Learn more about error responses.