Authentication

For authenticating requests with Stampede, Bearer Tokens are included in the request headers to ensure secure and authorised access. You generate these tokens using OAuth 2.0 client credentials flow. Your requests must include the Bearer Token in the headers like this:

authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

️ Rate Limiting: This endpoint operates a strict rate limit of 20 requests/minute. To avoid rate limit errors, follow the token caching best practices outlined below.

Generating a client_id & client_secret

You can generate a client_id & client_secret by heading to the Stampede dashboard > Marketplace > API Keys > Create New API Key.

From there, you'll be able to create a new client_id then in return will provide you with a client_secret. Keep it safe so it saves the hassle...

Generating a Bearer Token using OAuth 2.0 Client Credentials

Generate a Bearer Token

POSThttps://global.stampede.ai/oauth/token

Request Body

Name	Type	Description
`client_id`required	String
`client_secret`required	String
`grant_type`required	String	client_credentials

{
  "access_token": string,
  "expires_in": number,
  "token_type": "Bearer",
  "scope": "ALL:ALL"
}

Examples

curl --location 'https://global.stampede.ai/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
    "client_id": "ai.stampede.marketplace.example",
    "client_secret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "grant_type": "client_credentials"
}'

Token Caching & Expiry

Important: Tokens have an expiry time (indicated by the expires_in field in the response). Instead of requesting a new token for every API call, you should cache your token securely and reuse it until it expires. This significantly reduces requests to the authentication endpoint and helps you stay well within rate limits.

Best practices:

Cache the token in your application's memory or a secure cache (e.g., Redis)
Monitor the expiry time - refresh the token only when it approaches expiration
Reuse tokens across multiple API requests until they expire
Handle expiration gracefully - if a request returns an authentication error, obtain a fresh token and retry
Secure your cache - treat cached tokens as sensitive as your client_secret and ensure proper access controls