Getting an Access Token

This guide explains how to make your first Validation API request. You need SpotHero client credentials. Contact your SpotHero integration representative if you do not have them.

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://integrations.staging.spothero.com	https://accounts.stg.spothero.com/oauth/token	https://integrations.staging.spothero.com/
Production	https://integrations.production.spothero.com	https://accounts.spothero.com/oauth/token	https://integrations.production.spothero.com/

Use matching environment values

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

2. Request an access token

Send your client ID and client secret to the token URL:

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

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

The response contains an access_token. Keep it private. Do not put your client secret or token 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 example, check the staging API health:

GET https://integrations.staging.spothero.com/v2/healthcheck
Authorization: Bearer <access_token>

An HTTP 200 response means the API is reachable.

4. Make your first data request

List the facilities your client can access in staging:

GET https://integrations.staging.spothero.com/v2/facilities
Authorization: Bearer <access_token>

Save each returned facility_id. You need a facility ID to list or search its reservations. The next guide explains how to list facilities.

If a request fails

• 401 Unauthorized: request a new token and check that you use it as Bearer <access_token>. Replace an expired cached token.
• 403 Forbidden: check that your credentials are authorized for the Validation API and that you use the correct environment.
• 429 Too Many Requests: reduce how often you call the API.

For endpoint-specific responses and fields, see the API reference.