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:
Which style of authentication should you choose?
Let’s review each approach.
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:
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.
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:
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.
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.