This is an article on using our API. If you would like to configure Url Signing from the the StackPath portal, you may find more information in this article.
URL Signing allows you to protect your CDN assets by ensuring only authorized end users are able to access them. URL signing can be used to set an expiration time on a given URL, verify the URL was requested by the same IP address it was issued to, or 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.
To get started, you will need an API Key as well as your stack_id, site_id and scope_id.
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 /
Example:
{
"id": "4cfa711d-a665-46f4-b0x7-ffcf41370cf8",
"platform": "CDS",
"path": "/"
}
URL Signing Rule - Configurable Options
There are a handful of required fields when creating a URL signing Policy. There are also some additional fields as seen below:
{
"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"
}]
}
}
URL Signing Edge Rule - Create Rule
Next, we'll create the URL Signing Edge Rule to enforce the authorization token when fetching URL's. We will be creating this Edge Rule on your default scope so we'll need to restrict the rule to the appropriate pathFilter.
For example, if you wanted to enforce URL Signing on /signing/* you will use the following API call:
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"
}
'
How to use URL Signed URLs
Once you have enabled this configuration option here is how you can 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
You will need to encode the following portion of the URL: /videos/myfirstvideo.mp4?ttl=1534623693&passphrasefield=passphrase123
The URLs are encoded using 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 creating a post-encoded output of https://www.example.com/videos/myfirstvideo.mp4?ttl=1534623693&tokenfield123=8dcd148c1553d6a0b08c2dc3f6006c0e