Authentication methods

AvaTax uses basic HTTP authentication to connect to the API. 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’re building a connector that customers will set up and use on their premises, use Account ID/License Key authentication; otherwise, use Username/Password authentication.

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");

The table below describes how to construct an authentication token for AvaTax using your username and password.


Task	Result
Start with the word `Basic` followed by a `username`, a colon, and `password`. Don't include spaces between any values.	`Basic username:password`
Replace the `username` with your username, and the `password` with your password. Don’t include 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 Ym9iQGV4YW1wbGUub3JnOmJvYnNwYXNzd29yZGdvZXNoZXJI`
Add this to the `Authorization` header in your HTTP request.	`Authorization: Basic Ym9iQGV4YW1wbGUub3JnOmJvYnNwYXNzd29yZGdvZXNoZXJI`

License key authentication

Each AvaTax account has one (and only one!) license key. Because each account is tied to one environment, this means that a customer will typically have two license keys: one license key for Sandbox, and one license key for Production.

An account administrator generates a license key either through the Avalara Portal or by calling the AccountResetLicenseKey API.

Generate a license key using the API

When generating a license key using the AccountResetLicenseKey API, you must provide a valid account ID and set the confirmResetLicenseKey flag to true.

curl
  -X POST
  -H 'Accept: application/json'
  -H 'Authorization: Basic aHR0cHdhdGNoOmY='
  -H 'Content-Type: application/json'
  --data '{
    "accountId": 123456789,
    "confirmResetLicenseKey": true
  }'
  'https://sandbox-rest.avatax.com/api/v2/accounts/{id}/resetlicensekey'

Generate a license key through the Avalara Portal

Sign in to the Avalara Portal for the appropriate environment, go to Settings, and select Reset License Key.

As you’ll notice, this page is restricted to only account administrators. Keep in mind that you only have 1 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 Avalara calculation engine.


Task	Result
Start with the word `Basic` followed by `accountid`, a colon, and `licensekey`. There are no spaces between any values.	`Basic accountid:licensekey`
Replace `accountid` with your account ID, and `licenskey` with the license key you generated above. Ensure that you don’t include any whitespace characters - an account ID and a 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==`