1.2 - Authentication

• Previous
• Next

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 authentication
var 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:

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:

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.

Bearer Token Authentication

AvaTax is currently implementing support for OAuth 2.0 based bearer token authentication. This feature is available to select partners. To make use of the OAuth bearer token feature, please contact your account manager.

• Previous
• Next