API security

Free installs yandexmapslocator_api_* keys. The endpoint and kill switch activate after Pro. List rate limits also apply to Free search.php.

Pipeline

Request → ApiSecurityMiddleware (enabled, Bearer, rate limit, CORS) → parser → parent validation → controller → serializers → JSON + security headers.

Key settings

Key	Production recommendation
yandexmapslocator_api_enabled	Yes. Disable during an incident
yandexmapslocator_api_token	Long secret for server-side clients. Never written into locator HTML
yandexmapslocator_api_cors_origins	Exact frontend origins, not *
yandexmapslocator_api_allowed_parents	Restrict location containers
yandexmapslocator_api_resource_tvs	TV whitelist for include=tv
yandexmapslocator_api_trust_proxy	Yes only behind a trusted reverse proxy
yandexmapslocator_api_list_rate_limit	Tune for network load
yandexmapslocator_api_geocode_rate_limit	Geocoding costs Yandex quota

Full list: System settings.

Response headers

• Content-Type: application/json; charset=utf-8
• X-Content-Type-Options: nosniff
• List: Cache-Control: public, max-age=60 only if the token is empty, there is no Authorization header, and fields stay in the short public set. Otherwise private, max-age=60
• Successful geocode: Cache-Control: private, max-age=60
• Errors: Cache-Control: no-store
• CORS only from allowlist
• 429 + Retry-After: 60 when limit exceeded

Sample error bodies:

{
  "success": false,
  "error": "Unauthorized",
  "code": "unauthorized"
}

{
  "success": false,
  "error": "Rate limit exceeded",
  "code": "rate_limit_exceeded"
}

{
  "success": false,
  "error": "API is disabled",
  "code": "api_disabled"
}

What the API does not expose

REST does not include the Yandex Maps apiKey in JSON. On the snippet page the key only appears in the browser map script URL.

where is forbidden in REST and search.php.

Without Pro, product_id is cleared even if passed in the request.