This page describes how to authenticate with various SmartyStreets APIs. All requests must be authenticated.
There are two ways to authenticate your requests:
- secret keys Only for code running in a trusted environment.
To view your keys, and to generate new ones, log in to your account and go to the API keys page.
Embedded key are associated with one or more hostnames and/or IP addresses which you specify. Each of the hostnames (indicated by the 'Referer' header or 'Origin' header) will be granted rate-limited permission to call the API with the associated embedded key. For example, to use SmartyStreets on your website where
yoursite.com appears in the address bar, an embedded key like
3550738597428721952 must have the hostname
yoursite.com associated with it. Each Embedded Key may have a maximun of 100 hosts.
Each IP address associated with an embedded key is granted un-throttled access to the API with the associated embedded key.
Note that the host
yoursite.com is different from
www.yoursite.com and both must be associated with that embedded key in order for it to work on both hosts.
We also support wildcard subdomains; e.g.,
*.yoursite.com will work. (Note that
*.yoursite.com would not include
yoursite.com, so you would need to use both in this case.)
If you are working in localhost, you can simply add "localhost" (without the port number) as a host paired with your embedded key. If you do so, remember to delete "localhost" as a host as soon as possible, as it makes your embedded key more vulnerable to unauthorized use.
Using Embedded Keys
To authenticate API requests with an embedded key, include
key= and the embedded key in the query string. For example (line breaks have been added for readability):
https://us-street.api.smartystreets.com/street-address ?street=123+main+Schenectady+NY &key=4236410529599436
Example Use Cases: Embedded Key with Hostname
- An iOS or Android application (phone/tablet) that users download and install from an 'app store'. (These apps should be coded to set the HTTP 'Referer' header (or 'Origin' header) to a hostname/IP address listed with the embedded key.)
- A downloadable/installable application meant to be used in an untrusted desktop environment. (These apps should be coded to set the HTTP 'Referer' header (or 'Origin' header) to a hostname/IP address listed with the embedded key.)
Here's a good example of setting the referer in a cURL request:
curl -v "https://us-zipcode.api.smartystreets.com/lookup?key=3550738597428721952&city=mountain+view&state=CA&zipcode=94035" --referer https://10.212.22.45
Example Use Cases: Embedded Key with IP Address
When using public embedded key authentication (and depending upon the plan you are subscribed to), we restrict the number of requests coming from a given source over too short of a period of time. If you use embedded key authentication, you can avoid rate limiting by adding your IP address as an authorized host for the embedded 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.
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
Example Use Cases: Secret Keys
- A server-side web application which calls any of the SmartyStreets APIs from server-side code (PHP, .NET, Java, Python, Ruby, etc.).