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.
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:
- Navigate to the API Management page in the StackPath Customer Portal.
- Click or tap Generate Credentials.
- 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/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 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 IDname: The name your client credentials appears as in the StackPath Customer PortalclientId: Your credential's client IDclientSecret: Your credential's client secret
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 typeexpires_inWhen 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.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.stackpathapis.com/stackpath.rpc.RequestInfo",
"requestId": "acc298b3eed47389",
"servingData": ""
}
]
}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.stackpathapis.com/stackpath.rpc.RequestInfo",
"requestId": "6bedca3321373eb",
"servingData": ""
}
]
}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.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.
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 expiresiat: The UNIX timestamp when the token was issuediss: The host that issued the tokensub: 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 tohttps://identity.stackpath.com/accounts: A list of the StackPath account IDs that the token's user belongs tohttps://identity.stackpath.com/email: The email address of the user the token belongs tohttps://identity.stackpath.com/jti: The token's unique ID
Decode your JWT at https://jwt.io/ or using your preferred platform's JWT library.
Updated about a month ago