Chapter 1.2 - Authentication

Required Headers

These items must appear in your request header:

Key Value
api_key Base64 "username:password"
client_id Unique identifier for your company. Avalara provides this during account creation. Your Client ID is the same across all environments.
Content-Type application/json

Encode your API Key

The api_key is your Customer Portal "username:password" encoded in Base64. For example, if your username is and your password is secretpassword!, your api_key is Zmlyc3QubGFzdEBhdmFsYXJhLmNvbTpzZWNyZXRwYXNzd29yZCE=. The Communications REST v2 Swagger page automatically generates your api_key for you. To generate the api_key on the Swagger page:
  1. Enter your username in the email address field.
  2. Enter your password in the password field.
  3. Click the Generate api_key button.
The encoded api_key is populated in the api_key field. Copy and save this value for later use.
You can also encode a plaintext string to Base64 in Windows Powershell using the following script:
# Encode a string to Base64


If your api_key contains a "=" (for example, Zmlyc3QubGFzdEBhdmFsYXJhLmNvbTpzZWNyZXRwYXNzd29yZCE=), the cUrl statement in Swagger encodes the "=" special character to the ASCII "%3D" value (Zmlyc3QubGFzdEBhdmFsYXJhLmNvbTpzZWNyZXRwYXNzd29yZCE%3D). The "%3D" value is decoded to "=" during authentication and does not impact the authentication request.


Different factors can impact your api_key, namely different username capitalization. Usernames are not case sensitive, but passwords are. Base64 encoded values for usernames and are different but are treated as being identical behind the scenes during authentication. Base64 encoded values for passwords secretpassword! and SecretPassword! are different and cause authentication to fail because the password is not what is expected.

Optional Headers

Our tax engine allows for additional customization when calculating taxes through client profiles. For details about how client profiles work, see Customizing Transactions. For now, just know that you can pass an additional header to use a specific profile:
Key Value
client_profile_id An integer that specifies which profile you want to use when calculating the taxes in this request


If a client_profile_id is left blank, REST v2 uses the System Default configuration.