Guides

Quick start

StackPath provides a RESTful HTTP API for customers to programmatically interact with the StackPath platform. This API manages your account, stacks, and all of the services on them. Use the StackPath API to integrate StackPath's platform into your business and applications.

📘

StackPath's OpenAPI specs can be found here.

Requirements

A few things are required to get off the ground:

A StackPath account

StackPath's API is only available to StackPath customers. Register an account to get started.

API credentials

Your account must have API access in order to access the API. API access is guarded around credentials that are used to authenticate your calls. To generate your API credentials, perform the following:

  1. Navigate to the API Management page in the StackPath Customer Portal.
  2. Click or tap Generate Credentials.
  3. Record the Client ID and Client Secret in a secure location for later use. For security reasons the client secret is only shown to you when you generate your API credentials.

An HTTP client

Applications communicate with the StackPath API via HyperText Transfer Protocol (HTTP). As such, you need an HTTP client to make requests of the API. There are many clients out there, but use whichever makes most sense for your platform and application. The code examples in these guides use the curl command-line client.

📘

API call responses in these guides are shown with their full response headers and with JSON responses pretty-printed for easier readability. If you wish to see response headers in your curl calls then pass the -i or --include option to the curl command.

Authentication

StackPath API calls are authenticated with an OAuth2 bearer token. These tokens are generated from an API call that incorporates your StackPath account's client ID and client secret:

$ curl --request POST \
  --url https://gateway.stackpath.com/identity/v1/oauth2/token \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_type": "client_credentials"
  }'

Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your API client ID and client secret. This returns a response similar to the one below:

HTTP/1.1 200 OK
Date: Wed, 26 Feb 2020 23:21:19 GMT
Content-Type: application/json
Content-Length: 953
Connection: keep-alive
Vary: Accept-Encoding
Cache-Control: no-store
Pragma: no-cache
Strict-Transport-Security: max-age=15724800; includeSubDomains

{
  "access_token": "eyJhbGciOiJSUzI1...",
  "token_type": "bearer",
  "expires_in": 3600
}

The access_token field of this response is your bearer token. It should be used in the Authorization header of subsequent API calls to authenticate the call. Prepend your bearer token with the text Bearer in the Authorization header's value. This token is short lived and will need to be renewed after an hour. This is described in more detail on the Authentication page.

Making an API call

Now that you have a bearer token it's time to make an API call.

Finding your stack

Every service at StackPath is associated with a Stack. Stacks are collections of services that can be used for organization. Every account has a default stack on creation. Stacks are an integral part of every API call. To retrieve your account's stacks, place the following API call:

$ curl --request GET \
  --url https://gateway.stackpath.com/stack/v1/stacks \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_BEARER_TOKEN'

Replace YOUR_BEARER_TOKEN with the access_token value from your authentication call. It produces a response similar to:

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 part 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.

Creating a new CDN site

Create a new CDN site by placing an HTTP POST request to the API's site delivery service:

$ curl --request POST \
  --url https://gateway.stackpath.com/delivery/v1/stacks/YOUR_STACK_SLUG/sites \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
  --data '{
    "domain": "example.com",
    "origin": {
      "path": "/",
      "hostname": "example.com",
      "port": 80,
      "securePort": 443
    },
    "features": [
      "CDN"
    ]
  }'

As with the previous call, replace YOUR_BEARER_TOKEN with your bearer token value. Also replace YOUR_STACK_SLUG with the slug field returned by the previous call. This tells the API to create a new CDN site for the domain name example.com on the My Default Stack stack. It should produce a response similar to:

HTTP/1.1 200 OK
Date: Thu, 27 Feb 2020 00:54:57 GMT
Content-Type: application/json
Content-Length: 316
Connection: keep-alive
Vary: Accept-Encoding
Grpc-Metadata-Content-Type: application/grpc
Strict-Transport-Security: max-age=15724800; includeSubDomains

{
  "site": {
    "id": "414aafec-e508-49d5-8ebe-5b1e3258654d",
    "stackId": "74dd3b65-5f01-4b1e-8fcc-ad8443568af7",
    "label": "example.com",
    "status": "ACTIVE",
    "features": [
      "CDN"
    ],
    "apiLoginUrls": [],
    "shieldPopCodes": [],
    "createdAt": "2020-02-27T00:54:49.878509Z",
    "updatedAt": "2020-02-27T00:54:57.080636Z",
    "apiUrls": [],
    "monitoring": false
  }
}

Retrieving the new CDN site

Finally, you can retrieve the newly created site with an HTTP GET call to the site delivery service specifying the site ID:

$ curl -i --request GET \
  --url https://gateway.stackpath.com/delivery/v1/stacks/YOUR_STACK_SLUG/sites/YOUR_SITE_ID \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_BEARER_TOKEN'

As with the previous call replace YOUR_BEARER_TOKEN and YOUR_STACK_SLUG. In addition, replace YOUR_SITE_ID with the ID of the new site. The response from this call should match the response from the call that created the site:

HTTP/1.1 200 OK
Date: Thu, 27 Feb 2020 01:01:14 GMT
Content-Type: application/json
Content-Length: 316
Connection: keep-alive
Vary: Accept-Encoding
Grpc-Metadata-Content-Type: application/grpc
Strict-Transport-Security: max-age=15724800; includeSubDomains

{
  "site": {
    "id": "414aafec-e508-49d5-8ebe-5b1e3258654d",
    "stackId": "74dd3b65-5f01-4b1e-8fcc-ad8443568af7",
    "label": "example.com",
    "status": "ACTIVE",
    "features": [
      "CDN"
    ],
    "apiLoginUrls": [],
    "shieldPopCodes": [],
    "createdAt": "2020-02-27T00:54:49.878509Z",
    "updatedAt": "2020-02-27T00:54:57.080636Z",
    "apiUrls": [],
    "monitoring": false
  }
}

See the Sites and Content Delivery Network portions of the API reference for the StackPath API's full CDN capabilities.

Updated 4 months ago

What’s Next