US Street Address Authentication: API Key and Signature (2026)

Authentication overview

The US Street Address API, provided by Smarty, secures its endpoints through a credential-based authentication system. This system requires developers to use a unique API Key and an Auth Token (often referred to as a Signature) with each request. This method is designed to verify the identity of the calling application and ensure that only authorized accounts can access the address validation services. The use of two distinct credentials adds a layer of security, making it more difficult for unauthorized entities to compromise an account.

All communication with the US Street Address API occurs over HTTPS, which encrypts data in transit, protecting sensitive address information and authentication credentials from eavesdropping. This adherence to secure communication protocols is a standard practice for web APIs handling sensitive data, as outlined by organizations like the W3C Web Security FAQ.

Developers integrating the US Street Address API can manage their credentials through the Smarty account dashboard. The API supports various programming languages through official SDKs, simplifying the process of including authentication details in requests. The consistent application of these credentials across all API calls ensures that usage is tracked accurately and that service access remains tied to a valid, active subscription.

Supported authentication methods

The US Street Address API primarily relies on a combination of an API Key and an Auth Token for authentication. This approach is common in many web services for its balance of simplicity and security, particularly for API-to-API communication where user interaction for authentication is not feasible. The API Key identifies the account making the request, while the Auth Token provides cryptographic proof that the request is legitimate and authorized by that account.

It is crucial to understand that while a Website Key exists for certain client-side Smarty products like the US Autocomplete API, the US Street Address API itself requires the more secure API Key and Auth Token pair, which should always be handled server-side. Exposing the API Key and Auth Token in client-side code (e.g., directly in a browser's JavaScript) would compromise your account security, as these credentials grant full access to your API usage and potentially your account settings. For detailed guidance on securing your API keys, the Google Cloud documentation on safely using API keys provides relevant general principles.

Getting your credentials

To obtain the necessary API Key and Auth Token for the US Street Address API, you must first create an account with Smarty. The process typically involves:

1. Sign Up: Navigate to the Smarty homepage and register for a new account. A free tier offering 250 lookups per month is available for developers to test the service.
2. Access Dashboard: Once registered and logged in, you will be directed to your account dashboard.
3. Locate API Keys: Within the dashboard, there is usually a section dedicated to API Keys or Credentials. This section will display your unique API Key and Auth Token. Smarty's US Street Address API authentication documentation provides specific instructions on where to find these credentials.
4. Copy Credentials: Carefully copy both your API Key and Auth Token. These are sensitive credentials and should be treated with the same level of security as passwords.

It is important to note that Smarty may provide different types of keys for different services or environments (e.g., test keys vs. live keys). Always ensure you are using the correct credentials for your intended environment. If you suspect your credentials have been compromised, you should regenerate them immediately through your Smarty account dashboard.

Authenticated request example

When making requests to the US Street Address API, the API Key and Auth Token are typically passed as query parameters in the URL. Below is an example using cURL, demonstrating how to include these credentials in a request to validate a US street address. This example assumes placeholders for your actual API Key and Auth Token.

curl -X GET \
  "https://us-street.api.smarty.com/street-address?auth-id=YOUR_API_KEY&auth-token=YOUR_AUTH_TOKEN&street=1600+Amphitheatre+Pkwy&city=Mountain+View&state=CA&zipcode=94043" \
  -H "Accept: application/json"

In this example:

• auth-id is the query parameter for your API Key.
• auth-token is the query parameter for your Auth Token.
• The address components (street, city, state, zipcode) are also passed as query parameters.
• The Accept: application/json header requests the response in JSON format.

For integrations using one of the official Smarty SDKs (Python, JavaScript, PHP, Ruby, C#, Java, Go), the SDKs abstract away the direct handling of query parameters for authentication, allowing you to configure your credentials programmatically. For instance, in a Python SDK, you might initialize a client with your keys, and subsequent API calls would automatically include them.

from smarty_sdk.us_street import LookupClient

auth_id = "YOUR_API_KEY"
auth_token = "YOUR_AUTH_TOKEN"

client = LookupClient(auth_id, auth_token)

# Example lookup
result = client.lookup(
    street="1600 Amphitheatre Pkwy",
    city="Mountain View",
    state="CA",
    zipcode="94043"
)

print(result.json())

This Python example demonstrates how an SDK simplifies the authentication process, making it less prone to errors compared to manual URL construction.

Security best practices

Adhering to security best practices is essential when integrating any API, especially one that processes address data. For the US Street Address API, consider the following:

• Keep Credentials Secret: Your API Key and Auth Token are equivalent to passwords for your Smarty account. Never hardcode them directly into publicly accessible client-side code (e.g., JavaScript in a browser). They should be stored securely on your server or in environment variables.
• Use Environment Variables: Store credentials in environment variables rather than directly in your application's source code. This prevents them from being accidentally committed to version control systems like Git and makes it easier to manage different credentials for development, staging, and production environments.
• Restrict Access: Limit who has access to your API credentials within your organization. Implement role-based access control (RBAC) to ensure only authorized personnel can view or modify these sensitive keys.
• Secure Transmission (HTTPS): Always ensure that all requests to the US Street Address API are made over HTTPS. The API enforces HTTPS, but it's a critical check to ensure your application isn't inadvertently attempting insecure connections. HTTPS encrypts the data during transit, protecting your credentials and address data from interception.
• Monitor Usage: Regularly monitor your API usage through your Smarty account dashboard. Unusual spikes in usage could indicate unauthorized access or a misconfigured application.
• Rotate Credentials: Periodically rotate your API Key and Auth Token, especially if there's a change in personnel or a suspected security incident. Smarty's dashboard should provide functionality to regenerate these credentials.
• Implement Server-Side Validation: While the US Street Address API validates addresses, always implement your own server-side validation and sanitization of user-provided input before sending it to the API. This helps prevent various injection attacks and ensures data integrity.
• Error Handling: Implement robust error handling in your application to gracefully manage authentication failures. This can prevent sensitive information from being exposed in error messages and provide a better user experience.
• IP Whitelisting (if available): Check if Smarty offers IP whitelisting as an additional security measure. If so, configure your account to only accept API requests originating from your authorized server IP addresses. This significantly reduces the risk of unauthorized use even if your credentials are leaked. Refer to the Smarty documentation for available security features.