Element type: Required

Endpoints/models used: QueryCompanies

Your Configuration Dialog Window must allow the user to specify the following configuration/connection information:

Service URL to access the connector (for example, Production or Sandbox)
Login with Account Number/License Key or with Username/Password
Company Code dropdown with lookup

Configuring authentication

When configuring the authentication method, keep in mind that 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 isn’t user-specific and won’t expire if one user resets their password.
- All basic authentication headers are protected by strong SSL encryption in transit to Avalara.
Disadvantages:
- There’s only one license key for each account.
- Revoking your license key will cause all API calls with the old license key to fail.
- It isn’t possible to identify individual users taking an action when using license key authentication.

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

Tip

When designing a method for users to authenticate, consider providing a way to mask the password as the user is typing it, along with an option to show the password.

Configuring company code lookup

The QueryCompanies API is a method to test your connection. (Refer to the next topic.) This endpoint will retrieve either the single company that you configured and it to the form in your UI, or if you have multiple, it will return a dropdown list of your configured companies.

curl
    -X GET
    -H 'Accept: application/json'
    -H 'Authorization: Basic ${btoa(`:`)}''https://sandbox-rest.avatax.com/api/v2/companies'

Configuration window