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.
- In the portal, in the top, right corner, select your username.
- Select API Management.
- Click Generate Credentials.
- Enter a descriptive name for your credentials, and then click Save.
- 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
- 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.
- 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"
}]
}
}
Step 5: Create a URL signing EdgeRule
You must create a rule to enforce the authorization token when fetching URLs.
In this example, an EdgeRule will be created on a default scope, which indicates that the rule must be restricted to the appropriate pathFilter.
In the following example, the rule will enforce URL signing on /signing/* :
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"
}
'
Step 6: Build signed URLs
Review how to build signed URLs:
File | https://www.example.com/videos/myfirstvideo.mp4 |
TTL (optional) | Epoch time + 1 day (1534623693 at the time of this article) |
passPhraseField | passphrasefield (from example above) |
passPhrase | passphrase123 (from example above) |
Unencoded URL | https://www.example.com/videos/myfirstvideo.mp4?ttl=1534623693&passphrasefield=passphrase123 |
- Encode the following portion of the URL: /videos/myfirstvideo.mp4?ttl=1534623693&passphrasefield=passphrase123
- The URLs are encoded with MD5, so you can use the following command on a Mac to get the encoded piece:
echo -n "/videos/myfirstvideo.mp4?ttl=1534623693&passphrasefield=passphrase123" | md5
- The encoded piece is 8dcd148c1553d6a0b08c2dc3f6006c0e, which creates a post-encoded output of https://www.example.com/videos/myfirstvideo.mp4?ttl=1534623693&tokenfield123=8dcd148c1553d6a0b08c2dc3f6006c0e