Authentication

All Spot Thought APIs use API keys rather than Basic Auth or OAuth flows. Every request must provide the account’s API key, its matching secret, and (optionally) a target API version. Requests without valid credentials are rejected before they reach any business logic.

Creating API keys

Workspace administrators can generate keys in the Spot Thought Admin → Developers → API Keys screen. A key consists of:

API key (acct_...) – identifies the Spot Thought account (tenant) executing the call.
API secret (sk_live_...) – proves possession of the key. This is shown once; store it securely.

Rotate secrets regularly and delete keys you no longer need. Never embed the secret in mobile apps or distribute it to customer browsers.

Required headers

Send the following headers with every HTTP request:

Name
X-Spot-Api-Key
Type
string
Description
Your Spot Thought account identifier (for example acct_123).
Name
X-Spot-Api-Secret
Type
string
Description
The secret generated alongside the API key. Treat this like a password.
Name
X-Spot-Api-Version
Type
string
Description
Optional. Locks the request to a specific API version. Defaults to the latest stable version if omitted.

Example request

Authenticated cURL request

curl https://api.spot-thought.com/participants \
  -H "X-Spot-Api-Key: acct_123" \
  -H "X-Spot-Api-Secret: sk_live_abcd" \
  -H "X-Spot-Api-Version: 2024-11-15"

The same headers work for GraphQL and REST endpoints. If you omit X-Spot-Api-Version, the request is executed against the current default version; set it explicitly when rolling out breaking changes gradually.

Versioning strategy

API versions are date-based. When Spot Thought publishes a new schema you can pin your integration to the prior behavior by continuing to send the older date in X-Spot-Api-Version. When you are ready to upgrade, deploy the new version date alongside your application changes. If you omit the header entirely you automatically receive the latest contract.

Forwarded metadata

When requests flow through your infrastructure (Edge, CDN, or proxy), populate X-Forwarded-For and User-Agent so Spot Thought can retain the true source IP and client description. These values surface in audit trails and greatly speed up support investigations.