Deprecation of Query Parameter API Authentication (Action Required: Migration to Header-Based Authentication)

Effective 30 November 2026, we're implementing a critical security enhancement that requires your immediate attention to protect your API credentials and maintain the security of your applications. This update addresses the significant security vulnerabilities associated with passing sensitive credentials via URL query parameters, rather than securely within headers. 

Going forward, Vonage will now only support header-based authentication across APIs that require an API Key and API Secret to access. If you are currently not using the Vonage SDKs and making your API calls directly using query parameters in any API calls, you will need to update your code. If you are using the Vonage SDKs, make sure that you are on the latest version. JWT-based APIs will continue to work as normal.

Applies To

SMS,  Verify v1, Pricing v1, Number Insights v1, Conversions, Accounts, Other APIs if Query Parameters Authentication method is used.

What is Changing

Mandatory Migration: From Query String Authentication to Header-Based Authentication

Current Insecure Method (Being Deprecated):

# ❌ INSECURE - Credentials exposed in URL
curl "https://rest.nexmo.com/sms/json
?api_key=YOUR_API_KEY&api_secret=YOUR_API_SECRET&to=..."

New Secure Method (Required):

# ✅ SECURE - Credentials protected in headers
curl -X POST "https://rest.nexmo.com/sms/json" \
  -H "Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{"to": "...", "message": "..."}'

Note that in addition to switching to header-based authentication, some APIs, such as SMS, may require additional changes. For example, you will need to use a POST request and pass the SMS information as a JSON body, not just remove the `api_key` and `api_secret` parameters.

Please visit https://developer.vonage.com for the most up-to-date implementation information for each of the APIs.

Why This Change Is Critical

Security Vulnerabilities of Query String Authentication

1. Server Log Exposure

API credentials passed in query strings are stored in web server logs, which may not have the best security applied. Servers will often log/save query parameters for requests for a long time, but headers are much less widely stored.

2. Browser History & Sharing Risks

• Browser History: URLs with credentials get saved in browser history, meaning malicious code could sweep through a user's browsing history and extract passwords, tokens, etc.
• Accidental Sharing: Users might post the link, not realising what they've shared.
• Referer Header Leakage: URLs with credentials will be exposed in the "referrer" header when making requests to other domains

3. Proxy & Infrastructure Exposure

If you are using a proxy server, be it internal to your organisation or provided by a 3rd party, your API secret may get logged, as those are to be provided via the query parameters.

4. Browser Extension Access

Browser extensions can see query parameters from any site (if the user gives them permission) and use them however they like. Headers, cookies, POST bodies, etc., are only available to browser extensions on certain domains that the user explicitly allows.

What You Need to Do

1. Update Authentication Method

For Basic Authentication (API Key + Secret):

# Encode your credentials
echo -n "api_key:api_secret" | base64
# Use in Authorization header
curl -X POST "rest.nexmo.com/sms/json" \
  -H "Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS" \
  -H "Content-Type: application/json"

2. Code Migration Examples

JavaScript/Node.js

// ❌ Before: Insecure query string
const url = `https://rest.nexmo.com/sms/json
api_key=${apiKey}&api_secret=${apiSecret}`;
// ✅ After: Secure headers
const response = await fetch('https://rest.nexmo.com/sms/json', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${Buffer.from(`${apiKey}:${apiSecret}`).toString('base64')}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

Python

import requests
import base64
# ❌ Before: Insecure query string
# url = f"https://rest.nexmo.com/sms/json
?api_key={api_key}&api_secret={api_secret}"
# ✅ After: Secure headers
credentials = base64.b64encode(f"{api_key}:{api_secret}".encode()).decode()
headers = {
    'Authorization': f'Basic {credentials}',
    'Content-Type': 'application/json'
}
response = requests.post('https://rest.nexmo.com/sms/json', headers=headers, json=payload)

PHP

// ❌ Before: Insecure query string
// $url = "https://rest.nexmo.com/sms/json
?api_key={$apiKey}&api_secret={$apiSecret}";
// ✅ After: Secure headers
$credentials = base64_encode($apiKey . ':' . $apiSecret);
$headers = [
    'Authorization: Basic ' . $credentials,
    'Content-Type: application/json'
];
$response = curl_exec(curl_init([
    CURLOPT_URL => 'https://rest.nexmo.com/sms/json',
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true
]));

Java

// ❌ Before: Insecure query string
// String url = "https://rest.nexmo.com/sms/json
?api_key=" + apiKey + "&api_secret=" + apiSecret;
// ✅ After: Secure headers
String credentials = Base64.getEncoder().encodeToString((apiKey + ":" + apiSecret).getBytes());
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://rest.nexmo.com/sms/json"))
    .header("Authorization", "Basic " + credentials)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
    .build();

3. Update HTTP Method Where Necessary

• Change GET requests with credentials to POST requests with headers
• Use appropriate HTTP methods for your use case (GET for retrieval, POST for creation)
• Maintain RESTful principles while ensuring security

Note:

We recommend customers using the SMS API to consider migrating to the Messages API, which also supports JSON Web Token (JWT) authentication. Please find the SMS API to Messages API migration guide here. Customers interested in transitioning to the Messages API are encouraged to reach out to Sales or Support teams for a comprehensive overview of its technical capabilities.

Security Benefits

• Credentials not logged in standard web server logs
• Protected from browser history and sharing accidents
• Reduced exposure to proxy servers and monitoring tools
• Better compliance with security best practices

Industry Standards

• Alignment with OAuth 2.0 and modern authentication standards
• OWASP compliance for API security guidelines
• Reduced attack surface for credential theft
• Better audit trail for security reviews

Testing and Validation

Before deploying to production:

1. Test in a sandbox environment with header-based authentication
   1. [ ] No credentials in URL parameters
   2. [ ] Proper base64 encoding for Basic auth
   3. [ ] HTTPS used for all requests
   4. [ ] Headers properly formatted
   5. [ ] No credentials in client-side logs
2. Verify all API endpoints accept the new authentication method
3. Check application logs to ensure no credentials appear
4. Test error handling for malformed headers

Frequently Asked Questions

• Q: Can I use both methods during the transition? 

  A: Yes, during the grace period, both methods will work, but we strongly recommend migrating immediately for security.

• Q: Does this affect webhook URLs? 

A: Webhook signatures and verification remain unchanged. This only affects outbound API requests from your application to Vonage’s APIs.

• Q: What about existing integrations in production? 

A: Plan your migration carefully. Update development and staging environments first, then production during low-traffic periods.

• Q: What if I can't modify my application before the deadline? 

A: Contact our support team immediately to discuss your specific situation and potential alternatives.

Additional Information

Additional Security Recommendations

While migrating, consider implementing these additional security measures:

1. Regular Credential Rotation: Update API keys and secrets regularly
2. IP Allowlisting: Restrict API access to known IP addresses
3. Rate Limiting: Implement request throttling in your applications
4. Monitoring: Set up alerts for unusual API usage patterns
5. Audit Logging: Track all API authentication attempts

Applications not compliant after 30 November 2026 may experience authentication failures.

We're updating our documentation to provide clearer security guidance. 

If you need assistance with the implementation, please contact our support team.

Resources and Support

• Authentication documentation
• JWT Generator Tools
• Use jwt.io to validate your token structure
• https://api.support.vonage.com/hc/en-us/requests/new