Documentation

 

Authenticating

This page describes how to authenticate with the SmartyStreets API. All requests must be authenticated.

There are two ways to authenticate your requests:

  • Website keys For NON server-side code (typically Android or iOS mobile devices, Javascript-powered web sites, and/or desktop applications).
  • 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 tab.

Website Keys

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.

(Note that *.yoursite.com would not include yoursite.com, so you would need to use both in this case.)

Using website keys

Add an 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.

Example use cases: Website key with hostname

  • A website which calls any of our APIs using client-side Javascript (jQuery, angular, etc.).
  • A website which uses the SmartyStreets jQuery plugin (which is client-side Javascript).
  • A 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 to a hostname/IP address listed with the Website 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 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

Example use cases: Website key with IP Address

  • A website which calls any of our APIs using client-side Javascript which is used exclusively by agents in a call center of your organization. In this scenario, it is likely that usage of the API is frequent enough that it would be rate-limited if a hostname was used. Associating an IP address with your Website Key removes the rate limit.

Rate limiting

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.

Secret Keys

Secret keys must be kept secret (hence the name). This means they should not be embededded or exposed in HTML or Javascript of public-facing web applications or untrusted desktop and mobile applications. Use secret keys only in code executing in a trusted or controlled environment that connects directly to the various SmartyStreets APIs. A secret key is not limited to any particular hostname like website keys are. Secret keys consist of pair of values&mbash;an ID to identify your account along with a corresponding token which is like a password. While the ID value is safe to disclose over insecure or plaintext channels (such as emails to our customer service team), the token portion must remain secure and private at all times. WARNING: Disclosing, publishing, or broadcasting of secret key pair values is a direct violation of the Terms of Service and may be grounds for immediate termation of account privileges without prior notice or warning.

Using secret keys

To authenticate API requests with a secret key pair, specify auth-id and 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.).
  • A server-side web-application which calls any of the SmartyStreets APIs from Javascript code (Node.js).