Menu

Lumen help

Media portal support: API overview

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.

API style

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.

  • Every HTTPS API request must include all of the information required for the server to fulfill that request.

  • Each request is constructed to be complete, unless information is provided back to the server from the client within the new request.

  • Some API functions may be submissions for a process which will not be completed for several minutes, such as cache invalidation requests. For an invalidation request, the server might immediately accept the request and return a transaction ID. The client may then poll the server with the transaction ID for an update on the state of the request.

Default host

The default host for all API calls is: https://ws.lumen.com

Version number

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.

Getting started with Media portal APIs

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:
 

  1. Decide which API(s) you need to call.

    Use the list on the right to determine which Media portal APIs you will need to call. Write code to form the request and handle the response.

  2. Acquire an API key.

    An API key consists of a numeric ID and a secret. You can create and manage API security keys for CDN and Vyvx using Media portal.

Audience

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

API key characteristics

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:

  • Every API key is assigned a unique numerical ID by Media portal. This key ID is visible on the CDN API Security Keys page.
     

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.

  • An API key is authorized to access specific APIs based on the role assigned to the key. For more information about roles, see Role Management.

  • An API key is associated to a single access group.

  • The API key name is optional and can be modified by the administrator. Use this feature to simplify managing your keys. (For example, assign the key the name of the application that will use it.)

  • The secret is assigned by Media portal and can be regenerated as necessary. The secret is 160 bits in length and conforms to the requirements of constructing an RFC2104 HMAC-SHA1 digest.
     

If you believe that a third-party has gained knowledge of your API key secret, you should generate a new one immediately.

Authorization: roles and permissions

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.

Number of API keys

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.

  • If necessary, a user with the correct role and permissions can disable or re-enable an API key. Either event triggers an email to the user. When an API key is disabled, Media portal requires a note describing the reason for taking this action.

  • If one user disables a key, another user who has been assigned the API key permission at the same level access group or higher can re-enable it.

Key statuses

An API key can have one of the following statuses:

Status Description
Active Functioning.
Inactive
 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.

Rate limits

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.

API keys can be disabled

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.

Example

Whenever Media portal receives an API request, it follows this process:

  1. Authentication:

    • Is the API key ID recognized? If it is, continue. If not, reject the request.

    • Is the request signature valid? If it is, continue. If not, reject the request.

  2. Verify time stamp:

    • Does the time stamp in the request date to earlier than 15 minutes before the request receipt time? If not, continue. If so, reject the request.

  3. Enabled status:

    • Is the API key ID currently disabled? If not, continue. If so, reject the request.

  4. Request rate:

    • Is the rate of requests from this API key ID higher than the specified threshold? If not, continue. If so, reject the request.

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
 503 mpeRequestRateTooHigh
  1. Locate the Access Group ID. (Required for some API calls.)

    Because the access group name is editable, Media portal assigns an access group ID that does not change. The access group ID is required as part of the scope for some API requests, and the API key is used to locate this ID.

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:

  1. Send a request using the API key or access group interface. (See Key or Access Group Hierarchy.)

    The API: Key call returns the top-level access group; The API: Access Group Hierarchy call returns all access groups, including the top-level group.

  2. Locate the "assignedAccessGroup id" line in the response:


<apikey id="14816" xsi:noNamespaceSchemaLocation="https://ws.level3.com//schema/keyv1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <apiCorrelationId>API 421d15cd-0338-4eca-b644-8c85c9c4427</apiCorrelationId>
  <assignedAccessGroup id="1" name="Level3 Internal"/>
  <contact id="12345" name="email.address@level3.com"/>
  <role id="5" name="Admin"/>
  <status>Active</status>
  <credits>4999843</cedits>
  <next-top-up/>
</apikey>

  1. Add this ID to your API request.
  1. Determine which SCID or Network Identifier values to include in your URI syntax. (Required for some API calls.)

    If you are developing an API that includes a specific SCID or network identifier as part of the scope, you can determine these values using the Services Hierarchy API.

  2. Implement code to append a signature to the requests you send.

    Each request must be “signed” so it can be authenticated.

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 overview

API authentication is bi-directional between Lumen and the requestor.

  • Lumen's authentication is established by using a signed SSL certificate, allowing the caller to establish communications with the web services via HTTPS. The traffic exchanged is encrypted, preventing snooping of both CDN service-related data and the parameters required to construct the request signature.

  • The requester is authenticated by providing a signed HTTPS request to a specific URI/API, using the secret to generate a request signature.
     

Once the request is authenticated, the API key's authorization level is evaluated using the assigned role and rate limits.

Signature process

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:

  1. Selected information from your request, including certain HTTP request header fields, is combined into a string.

  2. A digest of that string is produced using the secret associated with your API key; this is the signature.

  3. The signature and the API key ID are placed in the HTTP authorization header, and the request is sent.

  4. Upon receiving the request, Media portal inspects the authorization header and extracts the API key ID.

  5. Media portal looks up the secret associated with that key. (The secret is known only by the key owner and Lumen.)

  6. Media portal gathers the other inputs to the digest and builds its own signature. If the two signatures match, the request is authenticated.

Signature format

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]
 

  • [Date]—value of the Date request header field formatted as, for example, Wed, 29 Apr 2015 +0000 using Java SimpleDateFormat, use: "EEE, dd MMM yyyy HH:mm:ss +0000" Java SimpleDateFormat using Locale.US), using Locale.US for the current UTC time. (See sample code for examples.)

  • “\n”—a line feed

  • [URI or RelativePath]—path of the request including request scope if applicable (access group, service, network IDs). The RelativePath should include the first forward slash (/) but should not include query string parameters. Examples:

    • /key/v1.0
    • /usage/v1.0/1234/BBB1234/my.property.com

  • [Content-Type]—value of the Content-Type request header field. For example:

    • text/xml
    • application/json

  • [HTTP-Verb]—HTTP method used for the request (e.g. “GET”, “PUT”, “POST”, “DELETE”).

  • [Content-MD5] (optional)—value of the Content-MD5 request header field, an MD5 digest of the request body. See RFC 2616 Section 14.15. If this request header is set, then it must be included in the signature string.
     

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

Unauthenticated requests are rejected and an HTTP status is sent. Unauthenticated requests include:

  • unsigned requests
  • requests not made over HTTPS
  • requests in which the date header value is older than 15 minutes

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.

API articles