Authentication and Authorization

Only authenticated requests to the REST API will be processed. This authentication process serves the following two purposes:

1. Identifies the user making the request.
2. Verifies that the user making the request has sufficient permissions to perform the requested action.

User authentication requires passing a unique value (i.e., token). The type of token that may be used to authenticate your requests varies according to whether the service is hosted on our API gateway.

• api.edgecast.com

  Requests to api.edgecast.com leverage a REST API token.

  Please contact your MCC administrator to request access to our REST API service. Upon approval, you will be allowed to generate and view tokens.

• API Gateway (api.vdms.io)

  Requests to our API gateway require a token generated from your OAuth 2.0 credentials. By default, this type of token expires after 300 seconds.

  Register your client application via the VDMS Identity dashboard to generate OAuth 2.0 credentials through which you may authorize requests submitted to our API gateway (api.vdms.io).

This section explains:

• REST API Token

  • Viewing a Token
  • Generating a Token
  • Authenticating Requests

• OAuth 2.0

  • Registering a Client Application
  • Generating Access Tokens
  • Authorizing Requests

REST API Token

Use OAuth 2.0 credentials to authorize requests to endpoints hosted on our API gateway (api.vdms.io). Requests to these endpoints cannot be authorized via a REST API token.
Learn more.

A REST API token is a unique alphanumeric value that identifies the user account through which the requested task will be performed. This ensures that only endpoints that have been authorized for that user account will be successfully completed.

A sample token value is shown below.

Viewing a Token

A REST API token is required to authenticate a REST API request. Generate and view your unique token(s) from the Web Services REST API Token section of the View Profile page.

Key information:

• The Web Services REST API Token section will not be displayed on that page when the current user account does not have sufficient privileges to use the REST API. Please contact a MCC administrator.

• MCC Administrator: A MCC administrator defines each user's level of access to the REST API.

  Learn more.

Generating a Token

As a best practice, the REST API token should be updated at regular intervals.

The recommended method for updating a REST API token involves the following steps:

1. Navigate to the View Profile page.

2. Click Edit.
3. Click Generate New Primary. When prompted, click OK to confirm this action.

4. From your preferred email client, open the verification email and then follow the verification link. The current primary token will be set as a backup token.

   Both primary and backup tokens provide the same level of access to the REST API.

5. Update existing applications to use the new token value.
6. Delete the backup token.

It is highly recommended that the backup token only be used to transition your existing applications to the new primary token.

Tokens that are no longer listed on the View Profile page cannot be used to authenticate to a REST API service.

Authenticating Requests

Setting up REST API request authentication requires setting the Authorization request header to your REST API token using the following syntax:

Key information:

• The term "TOK:" and the token value are not case-sensitive.
• An optional space character may separate the term "TOK:" and the token value.

• A request will not be authorized under the following conditions:

  • Missing/Invalid Token: Either the Authorization header was not specified or a properly formatted token value (see above) was not defined.
  • Insufficient Permissions: Your CDN administrator determines your level of REST API access by granting both HTTP methodRefers to the type of action being requested. Our REST API supports the use of the following methods: GET, POST, PUT, and DELETE. and user privileges.

• An unauthorized request will generate a 403 Forbidden response. The response body may indicate the reason why the request was deemed unauthorized (e.g., an invalid user was specified).

  Learn more.

Examples

Sample Authorization request headers are provided below.

Example #1:

Example #2:

OAuth 2.0

Authorization for our API gateway is managed by a centralized identity management solution called Identity Service (IDS). IDS leverages OAuth 2.0, which complies with the specification defined within RFC 6749, to authorize requests to the API.

Requests to our API gateway are authorized through the following workflow:

1. Access Token Request

   A client application requests API access from IDS. This request must include authentication information and a scope that defines the type of API requests that will be authorized.

2. Temporary Access Token

   If IDS is able to authenticate the client application, it will respond with a temporary access token set to the defined scope.

3. API Request

   The client application must then pass this access token via an Authorization header when submitting a request to our REST API.

4. API Response

   If the access token authorizes the requested action, then our REST API service will process it.

This workflow is illustrated below.

Registering a Client Application (Prerequisite)

Register your client application before interacting with REST API services hosted on our API gateway. Upon successfully registering your client application, the following information will be generated for your client application:

• Client ID: A value that uniquely identifies your customer account.

• Secret: This value authenticates the client application identified above.

  Do not expose the secret assigned to your account, since it may be used to impersonate your client application. For example, do not define your secret within a client-side script.

Generating Access Tokens

Each request to our REST API service must be authorized via an access token. Access tokens must be requested from IDS.

Access tokens provide temporary authorization (e.g., 5 minutes) to our REST API service. Once an access token expires, it may no longer be used to authorize requests. Attempting to authorize a request with an expired token will result in a 401 Unauthenticated Access response.

Request syntax:

Requests for access tokens requires a Content-Type header set to application/x-www-form-urlencoded.

Set the request body to:

Set the scope request body parameter to the desired scope. Common scopes are listed below.

Scope	Description
ec.rules	Authorizes full access to the Rules Engine service.
ec.analytics.rtap.reports	Authorizes full access to the Report Builder service.
ec.rtld	Authorizes full access to the RTLD service.
sec.cps.certificates	Authorizes full access to the Certificate Provisioning System service.

Sample request:

client_id=J23...BCdJ2345678-abcd-9012-efgh-34567890aBCd&client_secret=Fad...DFvFad323FSd4GSdce3DFv&grant_type=client_credentials&scope=ec.rules

Sample response:

{
	"access_token": "A1bcbGciOiJSUzI1NiIsImtpZCI6Ij13N1VGQ01z...A1bcbGciOiJSUzI1NiIsImtpZCI6Ij13N1VGQ01zOTIzQjI1MTYzRjU4MU1wQ0I3MUNBRDk3QjAzNkUwQjgiLCJ01XAiOiJKV1QiLCJ4NXQiOiJGMDc4bzVJN0pSWV9XQm9Ndcc5dGw3QTI0TGcifQ.1yJuYmYiOj11NjUzMDgwNzgsImV4cCI6MTU2NTMwODM3OCwiaXNzIjoiacR0ccM6Ly9pZC52ZG1zLmlvIiwiYXVkIjpbImc0dcBzOi8vaWQudmRtcy5pby9yZXNvdXJjZXMiLCJlYy5ydWxlcyJdLCJjbGllbnRfaWQiOiIxNTccOWZmZi04MTQzLTRmOW1tOWY1Yi1jNDgzZWVkNzclM2QiLCJzY29wZSI6WyJlYy5ydWxlcyJdfQ.XQ4TvzDrwLo4bO71cb1TbgYxmtcgTzC46Do0A9F3inAqw1qcr_Nr9IgRDxJDqR4Udc9QR86LVTQC2-ogGWP3pI12GtDtiUQdKYs5fpcuMf2Kbqau6kuU1M5BJm_GOcBNCCAJnU7SrDprVbPlwanGqk3yjcyo9nto8KWCRTwq2t31UQ1Ci31FZSr4vaMZJqk1vBW6NS3-yGowGCZbSIQBKpSgcc75coPtSjF1Qi6M4yORDyMC8c3KKlIp2b-6mpfDFXINIFV-XvnNuQ9v-lcc43_VWuDA_cQO8wmS4VzS1Ac1tpg1Pp4Bcdtjt12yKAXvi0X19R1BDmpxmO17cRRKYQ",
	"expires_in": 300,
	"token_type": "Bearer"
}

Authorizing Requests

Requests to our API gateway must be authorized via an access token. Specify an access token within the Authorization request header when submitting a request to our REST API service.

Authorization header syntax:

Key information:

• The term "Bearer" and the token value are not case-sensitive.

• An unauthorized request will generate a 401 Unauthorized response. The response body may indicate the reason why the request was deemed unauthorized. A request will not be authorized under the following conditions:

  • Missing/Invalid Token: Either the Authorization header was not specified or a properly formatted token value (see above) was not defined.
  • Insufficient Permissions: The scope associated with the token is insufficient for the requested action.
  • Expired Token: A token automatically expires after 300 seconds (i.e., 5 minutes). Once a token has expired, it can no longer authorize requests.

Examples

A sample Authorization request header is provided below.