1.2 - Authentication

AvaTax uses existing HTTP authentication standards: both basic HTTP authentication and OAuth 2.0 bearer token authentication. Both of these standards are well documented and have 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.

For HTTP Basic authentication, AvaTax supports two options:

  • Your AvaTax username and password
  • Your AvaTax account number and license key

Which style of authentication should you choose?

  • If you are building a connector that customers will set up and use on their premises, use Account ID/License Key authentication.
  • If you are building a web portal with direct AvaTax integration, please contact business development to see if bearer token authentication is the preferred approach.
  • Otherwise, use Username/Password authentication.

Let’s review each approach.

Username and Password Authentication

The simplest type of authentication uses a username and a password. If you use an AvaTax SDK, this encoding is done for you transparently. Just provide your credentials and the SDK will do all the work! For example, here’s how the AvaTax SDK for C# implements username/password authentication:

// Create a client and set up authenticationvar Client = new AvaTaxClient("MyTestApp", "1.0", Environment.MachineName, AvaTaxEnvironment.Sandbox)    .WithSecurity("MyUsername", "MyPassword");

If you are writing your own code, here’s how to construct an authentication token for AvaTax using your username and password:

Task Result
Start with the word Basic followed by username, a colon, and password. There are no spaces between any values. Basic username:password
Replace username with your username, and password with your password. Ensure that there are no whitespace characters unless those characters are part of your username or password. Basic bob@example.org:bobspasswordgoeshere
Now use your favorite Base64 encoding program to encode the right hand side of the string. Basic Ym9iQGV4YW1wbGUub3JnOmJvYnNwYXNzd29yZGdvZXNoZXJl
Add this to the Authorization header in your HTTP request. Authorization: Basic Ym9iQGV4YW1wbGUub3JnOmJvYnNwYXNzd29yZGdvZXNoZXJl

Basic username and password authentication has a number of advantages and disadvantages:

  • Advantages:
    • An auditor can uniquely identify the user that executed every API call.
    • 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.
  • Disadvantages:
    • Usernames and passwords can be stolen or forgotten.
    • 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.

Basic username and password authentication is recommended for individual users who are calling APIs within AvaTax, or for users who have limited access rights.

It’s worth restating here: A Sandbox username will not work in Production, and a Production username will not work on Sandbox. If you get a login failure, please check your username by logging onto the AvaTax website for sandbox or AvaTax website for production. That will help you determine which environment you should use.

Legacy License Key Authentication

Each AvaTax account has one (and only one!) legacy license key. Since each account is tied to one environment, this means a customer will typically have two license keys: one license key for sandbox, and one license key for production.

A license key is generated by an account administrator on the AvaTax website, or by calling the AccountResetLicenseKey API. For the moment, let’s focus on how to get a license key through the AvaTax website. Here’s how to generate a license key:

  • Log on to the AvaTax website for the appropriate environment.
  • 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 and Avalara is unable to recover this 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. However, generating a new key is a risk because this may affect existing systems using the AvaTax calculation engine.

Let’s construct an authorization using an Avalara License Key:

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. Ensure that there are no whitespace characters - an account ID and license key will never have whitespace characters of any kind. Basic 123456789:123456789ABCDEF123456789ABCDEF
Now use your favorite Base64 encoding program to encode the right hand side of the string. Basic MTIzNDU2Nzg5OjEyMzQ1Njc4OUFCQ0RFRjEyMzQ1Njc4OUFCQ0RFRg==
Add this to the Authorization header in your HTTP request. Authorization: Basic MTIzNDU2Nzg5OjEyMzQ1Njc4OUFCQ0RFRjEyMzQ1Njc4OUFCQ0RFRg==

Account ID/license key and username/password authentication are very similar in practice. So why would you choose one over the other? 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.
    • All basic authentication headers are protected by strong SSL encryption in transit to Avalara.
  • Disadvantages:
    • There is only one license key for each account.
    • 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.

Avalara recommends using account ID / License Key authentication when implementing connectors. Your software should have a configuration page or file that allows a customer to type in their account ID and license key when they set up your connector; then all API calls made through your connector will use these credentials.

PreviousNext