Getting an Access Token

This guide explains how to make your first Observations API request. You need SpotHero client credentials. Contact your SpotHero integration representative if you do not have them. Observations API requests also require the observations scope.

1. Choose an environment

Start in staging while you build and test your integration. Move to production only after your implementation is complete and tested in staging. When you switch, use the production token URL, audience, and API base URL together.

Environment	API base URL	Token URL	Audience
Staging	https://api.staging.spothero.com/v2/	https://accounts.stg.spothero.com/oauth/token	https://api.staging.spothero.com/v2/
Production	https://api.spothero.com/v2/	https://accounts.spothero.com/oauth/token	https://api.spothero.com/v2/

Use matching environment values

Use the token URL, audience, and API base URL from the same row. A staging token does not work with production, or the other way around.

Observations and Validation use different audiences

The Observations API uses a different base URL and audience from the Validation API. Use the exact values in this table.

2. Request an access token

Send your client ID and client secret to the token URL. This example uses staging and includes the required observations scope:

POST https://accounts.stg.spothero.com/oauth/token
Content-Type: application/json

{
  "client_id": "<your_client_id>",
  "client_secret": "<your_client_secret>",
  "audience": "https://api.staging.spothero.com/v2/",
  "grant_type": "client_credentials",
  "scope": "observations"
}

The response contains an access_token. Keep your client secret and token private. Do not put them in browser code, a repository, or a URL.

Save and reuse the token

The token endpoint is rate-limited. Request a token, save it securely, and reuse it for your API requests. Do not request a new token before every API request. Request a replacement shortly before the current token expires.

The token uses JWT format. You can read its expiration time from the exp value. The table below gives a general guide. Use the expiration time in your token when it is available.

Environment	Token lifetime	Suggested refresh time
Staging	24 hours	Every 23 hours
Production	24 hours	Every 23 hours

Keep the token in secure server-side storage. Do not expose it in a browser or other public location.

3. Send the token with each API request

Add the Bearer token to the Authorization header for each API request. The Observations API accepts POST requests at /facilities/observations. This is the authentication header to include:

Authorization: Bearer <access_token>

Observation requests also need a JSON body. See the Observations API reference for the complete request and response details.

If a request fails

• 401 Unauthorized: request a new token and check that you use it as Bearer <access_token>. Confirm the token includes the observations scope and uses the audience for the same environment as the API URL.
• 429 Too Many Requests: reduce how often you call the API.