API Security
Overview
Securing your integration with the Terra API is critical to protecting your account, your users, and the Tripadvisor content you serve. This guide covers the mechanisms Terra provides to keep your API traffic safe and the best practices every partner should follow.
Terra enforces security at multiple layers: TLS encryption in transit, API key authentication, per-account rate limits and daily quotas, endpoint authorization tied to your subscription, IP whitelisting, and an AWS WAF that filters malicious traffic before it reaches the application.
API Key Authentication
Every request to the Terra API must include a valid API key in the X-API-KEY header. The key uniquely identifies your Terra account and determines which endpoints and content tiers you can access.
Header format
X-API-KEY: YOUR_API_KEY
Include this header on every request. Requests without a valid key receive a 401 Unauthorized response.
| Scenario | HTTP Status | Error Message |
|---|---|---|
| API key missing from request | 401 | API key is not provided |
| API key not recognized | 401 | API key has not been found |
| API key disabled / account inactive | 401 | API key is not enabled |
| Key valid but endpoint not in subscription | 403 | API Key does not have access to endpoint |
Do not embed your key in client-side code, public repositories, or URLs. Store it in environment variables or a secrets manager and transmit it only over HTTPS.
HTTPS/TLS Encryption
All Terra API endpoints are served exclusively over HTTPS with TLS 1.2+. Plain-text HTTP requests are rejected. This ensures that your API key and all request/response data are encrypted in transit.
Make sure your HTTP client validates the server certificate. Do not disable certificate verification in production, even during debugging.
Regenerating Your API Key
If you suspect your API key has been leaked or compromised, regenerate it immediately. Regenerating creates a new key and invalidates the old one.
Steps to regenerated
- Log in to your Terra Dashboard at docs.terra.tripadvisor.com.
- Navigate to the Overview tab and locate the "My API Key" card.
- Click the regenerate / rotate button. A new key is generated instantly.
- Copy the new key and update it in all your applications and environment variables.
- Verify that your integration works with the new key before considering the migration complete.
Regenerating your key instantly revokes the previous key. Make sure you are ready to update every service or application that uses it before you regenerate. Plan for a brief service interruption or coordinate the update across your systems.
Endpoint Authorization
Your API key does not grant blanket access to every Terra endpoint. Access is controlled by your package (Discover, Growth, Scale, Innovate, Transform) and any add-ons you have enabled. Each package defines which API endpoints are authorized.
Attempting to call an endpoint outside your subscription returns403 Forbidden with the message "API Key does not have access to endpoint." To gain access to additional endpoints, upgrade your package or enable the relevant add-on in your Dashboard.
IP Whitelisting
Coming soon
Updated 6 days ago