StackPath IDs Explained
StackPath's API requires various ID types that define objects such as an account, a user, Stack, site, scope, etc.
This guide will explain the purpose of each of these IDs and where you can find them.
Account ID
An Account ID is used to define a specific StackPath account. Account IDs may be requested by Support for account lookups or for account verification purposes. You will need to obtain your Account ID by checking the Control Portal.
Follow the steps below for instructions on how to obtain your Account ID:
- Click on your name in the top right corner of the Control Portal, which will open up a drop-down menu. Click Profile.
- Click Account Information. This will open up a drop-down menu where you will find your Account ID. You can copy and paste this value when needed.
User ID
A User ID is used to identify a specific StackPath user. A user is anyone that can login to the StackPath customer portal or use the StackPath API. You will have to use the StackPath API to obtain the User ID.
To obtain this ID, you will first have to retrieve a list of all users on your account. You can retrieve all users by making a call to the Get all users endpoint. The list returned contains entries that are formatted as follows:
{
"id": "2f8fa0b2-fa54-4efa-af78-066a5f37eec6",
"email": "EMAIL",
"status": "ENABLED",
"identities": [],
"accounts": [],
"name": "NAME",
"phoneNumber": "PHONE_NUMBER",
"createdAt": "2019-12-23T14:30:35.439984Z",
"updatedAt": "2020-03-03T20:47:44.717808Z"
},
The User ID is located in first field named "id" at the top of this entry.
Stack ID
Every service at StackPath is associated with a "Stack". Stacks are collections of services that contain your sites, workloads, monitors, DNS records, etc. and are helpful at keeping your services organized. Every account has a default Stack upon creation.
Stacks are an integral part of every API call and are defined by their IDs or Slugs, either of which can be used in your API calls.
The Stack slug is located in the address bar of the Dashboard in the StackPath Control Portal:
https://control.stackpath.com/stacks/STACK_SLUG/dashboard
You can also retrieve all of your account's Stacks, along with their IDs and slugs, by making a call to the Get all stacks endpoint. Make sure you replace BEARER_TOKEN with your authentication token.
$ curl --request GET \
--url https://gateway.stackpath.com/stack/v1/stacks \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer BEARER_TOKEN'
This call produces a response similar to the following:
HTTP/1.1 200 OK
Date: Thu, 27 Feb 2020 00:34:28 GMT
Content-Type: application/json
Content-Length: 362
Connection: keep-alive
Vary: Accept-Encoding
Grpc-Metadata-Content-Type: application/grpc
Strict-Transport-Security: max-age=15724800; includeSubDomains
{
"pageInfo": {
"totalCount": "1",
"hasPreviousPage": false,
"hasNextPage": false,
"endCursor": "1"
},
"results": [
{
"id": "74dd3b65-5f01-4b1e-8fcc-ad8443568af7",
"accountId": "6129025b-bbb4-4218-a912-484c990e1c55",
"slug": "my-default-stack-0c13e2",
"name": "My Default Stack",
"createdAt": "2018-07-02T06:06:42.507271Z",
"updatedAt": "2018-07-02T06:06:42.507271Z",
"status": "ACTIVE"
}
]
}
The "pageInfo" section of the response is explained further in Pagination. Note the "id" and "slug" of the first returned Stack in the results array. Use this ID or slug in the URLs of future API calls to work with the services on this Stack.
Site ID
Each site that's added to our platform is assigned a site ID upon creation, which can be later used to define the site you'd like to retrieve, modify, delete, etc. via our API.
The site ID is located in the address bar of the Overview section in the StackPath Control Portal:
https://control.stackpath.com/stacks/STACK_SLUG/sites/SITE_ID/overview
You can also retrieve all of the sites on your Stack by making a call to the Get all sites endpoint. Make sure you replace STACK_ID with either your Stack ID or Stack slug and BEARER_TOKEN with your authentication token.
curl --request GET \
--url https://gateway.stackpath.com/delivery/v1/stacks/STACK_ID/sites \
--header 'Accept: application/json'
--header 'Authorization: Bearer BEARER_TOKEN'
This call produces a response similar to the following:
{
"pageInfo": {
"totalCount": "2",
"hasPreviousPage": false,
"hasNextPage": false,
"endCursor": "1"
},
"results": [
{
"id": "0ac0a3a7-ff9d-421f-8cce-4f3d55db93ae",
"stackId": "993aba44-1234-433d-be5d-72dbdf62f6a5",
"label": "domain.com",
"status": "ACTIVE",
"features": [
"CDN"
],
"createdAt": "2019-02-08T21:37:25.742801Z",
"updatedAt": "2019-02-08T21:37:32.312754Z",
"apiUrls": [],
"monitoring": false
},
{
"id": "7ccd03ec-7378-4737-84c8-c5e445a0202a",
"stackId": "b0a2127b-c846-4a65-b85a-07a389042ac2",
"label": "domain2.com",
"status": "ACTIVE",
"features": [
"CDN"
],
"createdAt": "2020-12-29T15:42:17.420854Z",
"updatedAt": "2022-05-25T18:11:15.517830Z",
"apiUrls": [],
"monitoring": false
}
]
}
The result above tells us that we have 2 active CDN sites on our Stack, domain.com and domain2.com. domain.com has the site ID 0ac0a3a7-ff9d-421f-8cce-4f3d55db93ae and domain2.com has the site ID 7ccd03ec-7378-4737-84c8-c5e445a0202a.
These site IDs can be used in subsequent API calls when required.
Scope ID
The StackPath API exposes a powerful CDN configuration system. Configurations are associated with a site's scopes. Scopes are a directory structure accessible over the CDN.
For example, in the URL http://www.domain.com/blog/styles.css, "/" and "/blog" are both valid scopes where individual configuration policies can exist. These configurations affect delivery of the assets within those directories.
Every scope has a platform and a path attribute which tell the CDN the incoming HTTP request path to map to. For most use cases, configuration should be tied to a site's root CDS scope, or the scope with the path value "/" and platform value "CDS".
CDS stands for "Content Delivery Service", and is the name of the platform StackPath uses to indicate that a scope should be used for CDN site traffic.
If you have sites in which WAF is enabled, then you may notice an additional path value containing "/wcs" listed in the sites' scopes. Regardless, the scope with the path value "/" and platform value "CDS" will continue to be the scope you most likely want to modify.
You can retrieve all configuration scopes associated with a site by making a call to the Get al scopes endpoint.
Remember to replace STACK_ID with your site's stack ID or stack slug, SITE_ID with your site's ID, and BEARER_TOKEN with your authentication token.
curl --request GET \
https://gateway.stackpath.com/cdn/v1/stacks/STACK_ID/sites/SITE_ID/scopes \
--header 'Authorization: bearer BEARER_TOKEN' \
--header 'Content-Type: application/json'
This request returns a JSON object that looks similar to the following:
{
"pageInfo": {
"totalCount": "2",
"hasPreviousPage": false,
"hasNextPage": false,
"endCursor": "1"
},
"results": [
{
"id": "289820e0-d634-415c-9d19-b4493a377f82",
"platform": "ALL",
"path": "/"
},
{
"id": "a1e0fa90-ad12-48a2-a8f9-24807866a5ee",
"platform": "CDS",
"path": "/"
}
]
}
The site's root CDS scope is the results value whose platform value is "CDS" and path value is "/". In this case, our root scope ID is a1e0fa90-ad12-48a2-a8f9-24807866a5ee.
For a site in which only WAF is enabled, the response would look similar to the following:
{
"pageInfo": {
"totalCount": "3",
"hasPreviousPage": false,
"hasNextPage": false,
"endCursor": "2"
},
"results": [
{
"id": "3b19f04b-2afe-4b93-a632-3b5ece0fe1d8",
"platform": "CDS",
"path": "/wds_50a0726a-6f11-4f3c-b7fa-e53f3537e21d"
},
{
"id": "a0fa839a-6f55-4b1a-9986-ef1587721b10",
"platform": "ALL",
"path": "/"
},
{
"id": "b08b288b-4fe1-41eb-8bd1-03d27fc5531c",
"platform": "CDS",
"path": "/"
}
]
}
Note that the scope with the "CDS" platform and "/" path is still present, which will be the scope we want to work with.
Updated 5 months ago
