Client Credentials Grant

Use the Client Credentials Grant to authenticate and authorize server-to-server operations

The Client Credentials grant type is typically used for server-to-server API operations. In this scenario, you are not acting as a Smokeball user but a type of “service” that can perform operations on an Account level.

Request an Access Token

Make a POST request to https://auth.smokeball.com/oauth2/token with the following parameters and headers:

curl

  curl --request POST 'https://auth.smokeball.com/oauth2/token' \
    --header 'Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'client_id=xxxx'

{
  "method": "POST",
  "url": "https://auth.smokeball.com/oauth2/token",
  "headers": {
    "Authorization": "Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=",
    "Content-Type": "application/x-www-form-urlencoded"
  },
  "body": {
    "grant_type": "client_credentials",
    "client_id": "xxxx"
  }
}

Authorization · string · required

Basic Authentication header containing the client_id and client_secret (base64-encoded).

Format: Basic base64(client_id:client_secret).

Example: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

Content-Type · string · required

Must be set to application/x-www-form-urlencoded. Ensures the request body is properly encoded.

grant_type · string · required

Must be set to client_credentials for this OAuth 2.0 flow.

Indicates the request is for client credentials grant.

client_id · string · required

The client identifier that has been issued.

Used to authenticate the client making the request.

The Authorization header must be the string “Basic” followed by your client_id and client_secret with a colon : in between, Base64 Encoded. For example, client_id:client_secret is Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "dmcxd329ujdmkemkd349r...",
    "expires_in": 3600,
    "token_type": "Bearer"
}

access_token · string

The token to use in the Authorization header when making API requests.

expires_in · number

The lifetime of the access token in seconds.

After expiration, a new token must be obtained.

token_type · string

The type of token returned. Always Bearer.

Caching Access Tokens

We recommend caching your access token and reusing it until it expires, rather than requesting a new token for every API request. Requesting a token on every request adds latency to each call and places unnecessary load on the token endpoint.

When you receive a token, store it along with its expiry time (calculated from expires_in, which is the token lifetime in seconds). Reuse the cached token for all API requests until it is close to expiry, then request a new one. A common approach is to refresh the token slightly before it expires (for example, 60 seconds early) to avoid using an expired token on an in-flight request.

See Making Requests - Server-to-Server requests for details on using Client Credentials.