Authentication in AvaTax REST v2

Authentication in AvaTax REST v2

The REST standard makes use of existing HTTP authentication methods rather than creating custom solutions. As a result, AvaTax V2, which uses the REST standard, supports Basic HTTP Authentication. This standard is well documented and has been in existence for a long time - which also means that over the past decades, many different people have implemented the standard in many different ways. Let’s describe exactly how to authenticate your API calls in AvaTax REST v2.

Additionally, we will talk a bit about the advantages and disadvantages of different types of authentication in order to help you select the correct type of authentication for your program.

Basic Authentication

The simplest type of authentication is called Basic HTTP Authentication, and it involves identifying yourself and providing a password. In order to use this API, you’ll need to know the following:

  • Your username, and
  • Your password.

That’s it! No magic. Here’s how to construct an authentication token for AvaTax REST v2 using your username and password:

Task Result
Start with the word "Basic" followed by username and password. 
Basic username:password
Replace "username" with your username, and "password" with your password. 
Basic bob@example.org:bobspasswordgoeshere
Now use your favorite Base64 encoding program to encode the right hand side of the string. 
Basic Ym9iQGV4YW1wbGUub3JnOmJvYnNwYXNzd29yZGdvZXNoZXJl

Now you’re done! Just paste your authorization header into the swagger online UI tester, or attach the authorization header to an HTTP request.

Basic Authentication has a number of advantages and disadvantages:

  • Advantages
    • Allows user actions to be audited to the user who did them.
    • Allows different users to have different privilege levels.
    • Basic authentication does not expire.
    • All basic authentication headers are protected by strong SSL encryption in transit to Avalara.
    • All Avalara APIs support basic authentication.
  • Disadvantages
    • Usernames and passwords can be stolen by viruses or trojans on a user's PC.
    • Insecure passwords can be guessed by brute force. To prevent this, Avalara enforces a limit: if you fail to authenticate multiple times in a row, your account may be locked out.

Overall, basic authentication is recommended for individual users who are calling APIs within AvaTax, or for users who have limited access rights.

License Key Authentication

Each AvaTax account has one (and only one!) license key. This license key is generated by an account administrator on the AvaTax Website. Here’s how to generate a license key:

  • Log on to the AvaTax Website
  • Click on Settings
  • Click on Reset License Key

As you’ll notice, this page is restricted to only account administrators. Keep in mind that you only have one license key! When you generate a new license key, all older license keys are immediately revoked and no longer usable. This is helpful because if your license key is lost or stolen you can revoke it instantly; it is a risk though because this may affect existing systems that are running at the moment.

To authenticate using a license key, here’s how you construct your authorization header:

Task Result
Start with the word "Basic" followed by accountid and licensekey. 
Basic accountid:licensekey
Replace "accountid" with your account ID number, and "licensekey" with the license key you generated above. 
Basic 123456789:123456789ABCDEF123456789ABCDEF
Now use your favorite Base64 encoding program to encode the right hand side of the string. 
Basic MTIzNDU2Nzg5OjEyMzQ1Njc4OUFCQ0RFRjEyMzQ1Njc4OUFCQ0RFRg==

As you’ll notice, license key and basic authentication are very similar in practice. Why would someone want to use license key authentication instead of username/password? Let’s look at the advantages and disadvantages of license key authentication.

  • Advantages
    • License keys have much stronger entropy when compared to a username/password, and are harder to attack.
    • Account ID / License Key authentication is not user-specific and will not expire if one user resets their password.
    • Basic authentication does not expire.
    • All basic authentication headers are protected by strong SSL encryption in transit to Avalara.
    • All Avalara APIs support basic authentication.
  • Disadvantages
    • There is only one license key for each company.
    • Revoking your license key will cause all API calls with the old license key to fail.
    • It is not possible to identify individual users taking an action when license key authentication is used.

I got an error message - what does it mean?

If you are working on authentication and you received an error message, here’s a breakdown of all REST v2 error codes and how to interpret them.

Recommendations

Overall, Avalara recommends:

  • If you are building a connector that customers will set up and use on their premises, use "Account ID/License Key" authentication.
  • Otherwise, use "Username/Password" authentication.