StackPath API calls are authenticated with an OAuth2 bearer token. These tokens identify the user calling the API and validate account ownership and permissions against the entities you want to modify.

API credentials

StackPath's API credential include:

• A client ID: A unique 32 character hexadecimal string.
• A client secret: A 64 character hexadecimal string. Client secrets should be treated like passwords. They're shown once when your API credential set is created, but are not shown in the customer portal or API after that.

Record your client ID and client secret in a secure place after they're created.

Creating API credentials

API credentials can be created in either the StackPath Customer Portal or the StackPath API. Creating API credentials is itself an authenticated call, so your first set of credentials must be created in the customer portal.

Using the customer portal

📘

This process is described in more detail at the StackPath Help Center.

To generate your API credentials in the StackPath Customer Portal, 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.

Using the StackPath API

Place a call to the /identity/v1/users/user_id/credentials endpoint to generate new API credentials:

$ curl --request POST \
  --url https://gateway.stackpath.com/identity/v1/users/YOUR_USER_ID/credentials \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
  --data '{
    "name": "My New API Credentials"
  }'

Replace YOUR_USER_ID with the requesting user's ID, and replace YOUR_BEARER_TOKEN with a bearer token generated from your existing credentials. The call produces a response similar to:

HTTP/1.1 200 OK
Date: Wed, 04 Mar 2020 00:39:08 GMT
Content-Type: application/json
Content-Length: 205
Connection: keep-alive
Strict-Transport-Security: max-age=15724800; includeSubDomains

{
  "id": "b109ea40-4603-417c-86fc-71548f319308",
  "name": "My New API Credentials",
  "clientId": "a2994b223...",
  "clientSecret": "52042a2ab..."
}

The response describes your new API client credentials:

• id: Your credentials' unique ID
• name: The name your client credentials appears as in the StackPath Customer Portal
• clientId: Your credential's client ID
• clientSecret: Your credential's client secret

Generating a bearer token

You need a bearer token to authenticate your StackPath API calls. Generate one from your API client ID and secret by placing a call to the /identity/v1/oauth2/token endpoint:

$ 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
}

This response contains the data:

• access_token: Your bearer token, a long string with hexadecimal (0-9, a-z) and period (.) characters in it.
• token_type: The OAuth2 bearer token type
• expires_in When the token will expire, in seconds. StackPath API tokens expire after one hour

If the client ID in the authentication request is missing or incorrect then a 404 Not Found error response is returned:

HTTP/1.1 404 Not Found
Date: Wed, 04 Mar 2020 00:20:53 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15724800; includeSubDomains

{
  "code": 5,
  "message": "record not found",
  "details":[
    {
      "@type": "type.stackpathapis.com/stackpath.rpc.RequestInfo",
      "requestId": "22a6cbb712342bdd",
      "servingData": ""
    }
  ]
}

If the client ID is correct but the client secret is missing or incorrect then a 401 Unauthorized response is returned:

HTTP/1.1 401 Unauthorized
Date: Wed, 04 Mar 2020 00:24:46 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Strict-Transport-Security: max-age=15724800; includeSubDomains

{
  "code": 16,
  "message": "invalid_client",
  "details":[
    {
      "@type": "type.stackpathapis.com/stackpath.rpc.RequestInfo",
      "requestId": "acc298b3eed47389",
      "servingData": ""
    }
  ]
}

Using your bearer token

Add your bearer token to your request's Authorization header, prepended by the text Bearer and a space to authenticate your API calls:

$ 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 your bearer token in the above example. If the Authorization header isn't provided then a 401 Unauthorized error response is returned:

HTTP/1.1 401 Unauthorized
Date: Wed, 04 Mar 2020 00:02:53 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Strict-Transport-Security: max-age=15724800; includeSubDomains

{
  "code": 16,
  "message": "Request unauthenticated with Bearer",
  "details": [
    {
      "@type": "type.stackpathapis.com/stackpath.rpc.RequestInfo", 
      "requestId": "6bedca3321373eb",
      "servingData": ""
    }
  ]
}

Token expiry

StackPath bearer tokens live for one hour. API requests return a 401 Unauthorized response when the token is expired:

HTTP/1.1 401 Unauthorized
Date: Tue, 03 Mar 2020 23:44:15 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Strict-Transport-Security: max-age=15724800; includeSubDomains

{
  "code": 16,
  "message": "token is expired by 0h10m37s",
  "details": [
    {
      "@type": "type.stackpathapis.com/stackpath.rpc.RequestInfo",
      "requestId": "2993aafc4fb01906",
      "servingData": ""
    }
  ]
}

Generate a new token from your API client ID and secret to continue using the StackPath API. We recommend checking if your existing token is expired and re-authenticating before placing your call to avoid service interruption.

Peeking into the bearer token

Your bearer token is a JSON Web Token (JWT) and contains information about your StackPath account and authentication session. JWTs contain a header, payload and signature.

The JWT header and signature

The header describes the type of token and the signing algorithm used to generate it. StackPath bearer tokens are generated using the RS256 algorithm (an RSA signed SHA-256 hash). The signature is the binary hash used to sign the token.

The JWT payload

Your bearer token's JWT payload contains useful information about your token and the user and account that generated it:

{
  "aud": "https://gateway.stackpath.com",
  "exp": 1582767218,
  "iat": 1582763618,
  "iss": "identity.stackpath.com",
  "sub": "stackpath|b567f809-9910-4997-8ea4-4da0c72bd86a",
  "https://identity.stackpath.com/accounts": [
    {
      "id": "369ae85d-67df-4cc5-8b48-bdd3635cbda3"
    }
  ],
  "https://identity.stackpath.com/email": "jdoe@example.com",
  "https://identity.stackpath.com/jti": "7b309edc-e234-4399-a6cb-2030cf269383"
}

The payload contains a number of claims, or bits of information declared in the token:

• aud: The audience that can accept the token, in this case StackPath's API host https://gateway.stackpath.com.
• exp: The UNIX timestamp when the token expires
• iat: The UNIX timestamp when the token was issued
• iss: The host that issued the token
• sub: The token's subject, in this case the name of entity that issued the token followed by a vertical pipe then the ID of the user that the token belongs to
• https://identity.stackpath.com/accounts: A list of the StackPath account IDs that the token's user belongs to
• https://identity.stackpath.com/email: The email address of the user the token belongs to
• https://identity.stackpath.com/jti: The token's unique ID

Decode your JWT at https://jwt.io/ or using your preferred platform's JWT library.