This page describes how to authenticate with the SmartyStreets API. All requests must be authenticated.
There are two ways to authenticate your requests:
- Secret keys Only for server-side code.
To view your keys, and to generate new ones, log in to your account and go to the API Keys tab.
Website keys are associated with one or more hostnames and/or IP addresses which you specify. Each of the hostnames will be granted rate-limited permission to call the API with the associated website key. For example, to use SmartyStreets on your website where
yoursite.com appears in the address bar, a website key like
3550738597428721952 must have the hostname
yoursite.com associated with it.
Each IP address associated with a website key is granted un-throttled access to the API with the associated website key.
(Note that the host
yoursite.com is different from
www.yoursite.com and both must be associated with that website key in order for it to work on both hosts.)
We also support wildcard subdomains, e.g.
*.yoursite.com will work.
*.yoursite.com would not include
yoursite.com, so you would need to use both in this case.)
Using website keys
auth-id parameter to the query string of your requests. Set the value of the
auth-id parameter to the desired numeric website key from your website keys listing. For example (line breaks added for readability):
https://us-street.api.smartystreets.com/street-address ?street=123+main+Schenectady+NY &auth-id=3550738597428721952
Note: When calling any of our APIs using "Website Key" authentication, only the HTTP GET method is allowed.
Use cases: Website key with hostname
- A phone/tablet app that users download and install from an 'app store.' (These apps should be coded to set the HTTP 'Referer' header to a hostname/IP address listed with the Website Key.)
Here's a good example of setting the referer in a cURL request:
curl -v "https://us-zipcode.api.smartystreets.com/lookup?auth-id=3550738597428721952&city=mountain+view&state=CA&zipcode=94035" --referer https://10.212.22.45
Use cases: Website key with IP Address
When using public "website key" authentication, we restrict the number of requests coming from a given source over too short of a period of time. If you use "website key" authentication, you can avoid rate limiting by adding your IP address as an authorized host for the website key in question. This is done in order to prevent runaway charges caused by such conditions as a misbehaving (infinite) loop sending the same record over and over to the API. You're welcome.
Key pairs must be kept secret, so they should not be used on client-side HTML or in client-side applications. Use secret key pairs on server-side code that connects directly to the SmartyStreets API servers. A secret key pair is not limited to any particular hostname like website keys are. A key pair consists of an ID to identify your account and a token which is like a password.
Using secret keys
To authenticate API requests with a secret key pair, specify
auth-token, containing the URL-encoded ID and associated token, respectively. For example (line breaks have been added for readability):
https://us-street.api.smartystreets.com/street-address ?street=123+main+Schenectady+NY &auth-id=8d497be5-e211-4949-a18f-0bfd1d9970d3 &auth-token=th4hargQiuyG7w7L7xfO
Use cases: Secret keys
- A website which calls any of our APIs from PHP code (which is executed server-side).
- A website which calls any of our APIs from server-side code (.NET, Java, Python, Ruby, etc.).
- Any script or code executed from within your organization that directly calls the SmartyStreets API servers.