Configure Basic URL Signing via API Call

Overview

You can use this document to learn how to configure URL signing via the StackPath API.

Note:

This article focuses on how to use the API for URL signing. To learn how to use the StackPath Control Portal to perform the same action, see EdgeRules: Configure URL signing from the Control portal. 

You can use URL signing to protect your CDN assets by ensuring that only authorized end users are able to access your assets. 

URL signing can be used to:

• Set an expiration time on a given URL
• Verify the URL was requested by the same IP addresses that issued the URL
• Only allow certain user agents to access your URLs

Assets delivered with URL signing enabled use an MD5 hash appended to the URL to validate that access should be granted.

Step 1: Obtain an API key

To use the StackPath API system, you must create an API key for authentication purposes. 

Note: API keys have the same permission as the user who generates them. As a result, admins should not generate API keys for their users. 

1. In the portal, in the top, right corner, select your username.
2. Select API Management.
3. Click Generate Credentials. 
4. Enter a descriptive name for your credentials, and then click Save. 
5. Copy and save the Client ID and API Client Secret string in a secure location place.
   • The API Client Secret is only displayed once. After you close the pop-up window, you will not be able to retrieve the key. 
   • If you lose this key, then you must generate a new key. 

To learn more about the StackPath API system, including how to authenticate, visit the StackPath Developer Portal.

Step 2: Obtain the stack_id and site_id 

1. To obtain the stack_id, run: GET https://gateway.stackpath.com/stack/v1/stacks
   • To learn more, visit the StackPath Dev Portal and see Stacks.
2. To obtain the site_id, run: GET https://gateway.stackpath.com/delivery/v1/stacks/stack_id/sites
   • To learn more, visit the StackPath Dev Portal and see Sites.

Step 3: Obtain the scope_id

To obtain your scope_id you can use the following API call:

curl -H 'Authorization: Bearer <your_token>' -X GET 'https://gateway.stackpath.com/cdn/v1/stacks/<stack_id_here>/sites/<site_id_here>/scopes' -H 'accept: application/json'

From this list, you will want the scope labeled CDS with path /, such as: 

 {
 "id": "4cfa711d-a665-46f4-b0x7-ffcf41370cf8",
 "platform": "CDS",
 "path": "/"
 }

Step 4: Review configuration options for URL signing rule 

When you create a URL signing policy, there are some required configurations, as well as some optional configurations. 

Review the list below to understand your configuration options:

{
  "configuration": {
    "authUrlSign": [{
      "id": "string", 
      "tokenField": "string",      // Required
      "ignoreFieldsAfterToken": true,
      "passPhraseField": "string", // Required
      "passPhrase": "string",      // Required
      "expiresField": "string",
      "ipAddressField": "string",
      "uriLengthField": "string",
      "userAgentField": "string",
      "enabled": true,             // Required
      "methodFilter": "string",
      "pathFilter": "string",
      "headerFilter": "string"
     }]
   }
}

curl -H 'accept: application/json' -H 'Authorization Bearer <your_token>' \
-X POST 'https://gateway.stackpath.com/cdn/v1/stacks/:stack_id/sites/:site_id/scopes/:scope_id/rules' -d '
{
 "configuration": {
 "authUrlSign": [{
  "tokenField": "tokenfield123",
  "ignoreFieldsAfterToken": true,
  "passPhraseField": "passphrasefield",
  "passPhrase": "passphrase123",
  "enabled": true,
  "pathFilter": "signing/*"
  }]
 },
 "name": "URL Signing on signing",
 "slug": "url-signing-on-signing"
 }
'

echo -n "/videos/myfirstvideo.mp4?ttl=1534623693&passphrasefield=passphrase123" | md5