Authentication best practices

This guide outlines authentication best practices to minimize authentication errors, reduce latency, and enhance security when integrating with our APIs. Following these guidelines will help you maintain reliable connections, improve performance, and protect sensitive data.

Authentication methods

Booking.com currently supports two authentication methods.

• Credential-based authentication
• Token-based authentication

Credential-based authentication

Always send authorization requests with valid credentials. Sending requests with missing or incorrect credentials returns a 401 Unauthorized error message, which increases processing overhead and introduces latency.

Consider the following best practices when implementing credential-based authentication:

• Store credentials securely (never in plaintext or client-side code).
• Use environment variables for credential storage in development.
• Use secrets management solutions in production environments.
• Implement credential rotation policies.

Token-based authentication

Token-based authentication offers improved security and performance compared to sending credentials with each request.

Implementation steps:

1. Generate a fresh token (JWT) using your API credentials.
2. Include the token in subsequent API calls.
3. Implement token renewal before expiration (every 1 hour).
4. Handle token validation and errors appropriately.

JWT structure and validation:

• JWTs consist of three parts: header, payload, and signature. For detailed information on the payload, see the Standard claims section.
• Always validate token expiration (found in the payload) before making requests.
• Store tokens securely and never expose them in client-side code.

Credential management

Proper credential management is essential for maintaining security and system availability.

Best practices

Consider the following best practices when managing credentials:

• Implement credential rotation on a regular schedule
• Use different credentials for development and production environments
• Monitor failed authentication attempts
• Revoke compromised credentials immediately
• Use the principle of least privilege when assigning access permissions

IP allowlists

The following section contains best practices to consider when implementing IP allowlists.

Drawbacks of using IP allowlists

Creating and using an IP allowlist restricts access to a system or API by allowing only predefined IP addresses to make requests. Any request originating from an IP address not on the allowlist (even with valid credentials) is automatically rejected with a 401 Unauthorized response.

Key drawbacks:

• Legitimate users may be locked out if their IP changes.
• Attackers attempting access from unapproved IPs can generate excessive 401 errors.
• Excessive 401 responses can flood logs, masking real security threats.
• Support teams may face additional requests from users unable to authenticate.
• Dynamic IP allocation can cause intermittent authentication failures.

Mitigating issues when using IP allowlists

The following best practices can help resolve issues when using IP allowlists:

• Use token-based authentication: Implement token-based authentication to reduce dependency on IP-based security.
• Verify Outbound IP address: Check your public IP using https://api64.ipify.org or https://ifconfig.me and compare it with the allowlist.
• Use a Static IP address: If dynamic IPs cause issues, consider obtaining a static IP from your Internet Service Provider.
• Ensure Correct VPN/Proxy usage: Verify you're using the correct VPN or proxy to maintain a consistent allowlisted IP.
• Check API Client configuration: Ensure API clients are correctly configured to send requests from the expected network.
• Implement VPN tunnels: Require users to connect through a VPN before accessing protected resources.
• Consider IP range allowlisting: Instead of individual IPs, allowlist IP ranges when appropriate.

Rate limiting and error handling

Our authentication system implements rate limiting to prevent abuse. Excessive authentication requests can trigger rate limits, resulting in 429 Too Many Requests errors. The token-based authentication endpoint accepts 30 calls per hour.

Consider the following best practices when addressing rate limit errors:

• Implement exponential backoff for retries
• Cache authentication tokens to reduce authentication requests
• Monitor rate limit headers in responses
• Distribute load across multiple credentials if available

Troubleshooting

Common Authentication errors

Debugging Authentication issues

• Enable verbose logging in your authentication client.
• Check system time synchronization especially when using token validation.
• Verify network connectivity to authentication endpoints.
• Confirm whether you are using the correct environment settings (dev/prod).