Authentication

The API base URL is https://caravanguide.co.uk/api/v1/. All requests must be made over HTTPS. The API supports two authentication mechanisms. Both are machine-to-machine only - there is no user-session or browser-based auth on the API.

1. API Key (`X-API-Key`)

Static API keys are the simplest integration option. Pass the raw key in the X-API-Key request header on every request.

GET /api/v1/valuations/search?manufacturer=Swift&model_name=Challenger&model_year=2020 HTTP/1.1
Host: caravanguide.co.uk
X-API-Key: cg_live_a1b2c3d4e5f6...

Keys are prefixed with the environment: cg_live_ for live, cg_sandbox_ for sandbox.

Keys are stored as an HMAC-SHA256 hash on the server - they cannot be retrieved after creation. If a key is lost, issue a new one and revoke the old one via your account manager.

2. OAuth 2.0 Client Credentials

OAuth 2.0 is the recommended approach for applications that manage token lifecycle. The flow is:

Exchange your client_id and client_secret for a short-lived Bearer token.
Use the Bearer token for API requests until it expires.
Re-request a new token when the old one expires (there are no refresh tokens).

Step 1 - Obtain a Token

POST /api/v1/oauth/token HTTP/1.1
Host: caravanguide.co.uk
Authorization: Basic BASE64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=valuations%3Aread

The scope parameter is optional. If omitted, all scopes granted to the client are included. Requested scopes must be a subset of your granted scopes.

Token Response

{
  "access_token": "eyJr...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "valuations:read"
}

Step 2 - Authenticate Requests

GET /api/v1/valuations/catalog?bootstrap=1&manufacturer=Swift&model_name=Bordeaux&model_year=2017 HTTP/1.1
Host: caravanguide.co.uk
Authorization: Bearer eyJr...

GET /api/v1/valuations/search?manufacturer=Swift&model_name=Bordeaux&model_year=2017 HTTP/1.1
Host: caravanguide.co.uk
Authorization: Bearer eyJr...

Catalogue and resolve endpoints use the same authentication as search. See Partner catalogue workflow for integration patterns.

Token Endpoint Rate Limit

The token endpoint has a hard rate limit of 10 requests per 60 seconds per client, regardless of your tier. Cache your token and only re-request when it is close to expiry.

IP Allowlisting

Optionally, your credentials can be locked to a set of CIDRs. Requests from IPs outside the allowlist return 403 ip_not_allowed. Contact your account manager to add or update IP restrictions.

Scopes

Scope	Access
`valuations:read`	Search valuations, catalogue cascade (step + bootstrap pre-fill), resolve aliases, pricing history
`certificates:read`	Verify certificates, view history by VIN
`certificates:write`	Issue new certificates (enterprise only)
`trust_badge:read`	Check trust badge status and verification
`parks:read`	List and detail caravan parks

Your credentials are granted only the scopes negotiated during onboarding. Using an endpoint that requires a scope your credential doesn't have returns 403 scope_missing.

HTTP Status Semantics

Status	Meaning
401	Credential not found, malformed, or expired - re-authenticate
403	Credential valid but access explicitly denied (revoked, wrong scope, IP block, commercial restriction)
429	Rate limit or monthly allowance exceeded
503	Endpoint disabled by kill-switch or platform maintenance