> ## Documentation Index > Fetch the complete documentation index at: https://docs.oleria.com/llms.txt > Use this file to discover all available pages before exploring further. # Avalara AvaTax > Connect Avalara AvaTax to Oleria to bring AvaTax users and their security roles, companies, license keys, accounting-firm access and audit activity into your identity and access graph. Connect Avalara AvaTax to Oleria to see who can sign in to your AvaTax account, which companies each person can reach and with which security role, which license keys can call AvaTax on your account's behalf, and which accounting firms manage your account. Oleria reads this from the AvaTax REST API with an account ID and license key, or with the username and password of a dedicated AvaTax user. You can review access to your tax platform and take action directly from Oleria. ## What Oleria discovers Once connected, Oleria continuously discovers and maps the following from your AvaTax account: * **Accounts** - every AvaTax user. Oleria imports each user's name, email address, username, security role, home company, and status. Active users are enabled. Inactive users are imported as disabled. Users with an administrator role, such as **AccountAdmin** or **CompanyAdmin**, are marked as administrators. If your account uses SAML single sign-on, Oleria records single sign-on as configured. * **Non-human identities (NHIs)** - every named license key on the account, imported as an API token. Oleria records when each key was created and by whom. The license key this integration uses is marked as the connection's own key when you enter its name. * **Secrets** - each license key is also imported as a secret. A license key has no scopes and never expires, so it's recorded with full authority over the account. Oleria never reads or stores a key's value. * **External accounts** - each accounting firm with an approved link to your account. A linked firm's users can see and manage every company in your account from their own Avalara account. * **Roles** - every security role held by at least one user, with the users who hold it. * **Resources** - every company in your account, with its parent and child companies. Oleria maps which users, license keys, and accounting firms can reach each company, and with which role. A user with an account-wide role reaches every company. A user with a company role reaches their home company and its child companies. Company administrators are recorded as the managers of their home company. * **Activity** - two AvaTax audit sources: * **Failed API calls** - every AvaTax API call that returned an error, including calls rejected for bad credentials and permission denials. Failed calls that Oleria makes are included and marked as Oleria's. * **Configuration changes** - changes to users, companies, and account and company settings, such as a user being deactivated or given a new security role. Oleria attributes each event to the AvaTax user who made it. AvaTax records a license key's calls under a hidden user that its API doesn't list, so Oleria can attribute only the license key this integration uses, and only if you enter its **License key name**. Events made with other license keys, or by deleted users, show no actor. Activity trails real time by about an hour. Oleria refreshes this data on its [regular sync schedule](/integrations/overview.md#sync-model). > [!NOTE] > > Oleria doesn't import transactions, tax codes, items, customers, exemption certificates, or other tax data. This integration covers identity and access governance for AvaTax users, license keys, accounting-firm access, companies, and security roles. ## Prerequisites * An AvaTax account administrator who can create license keys or users. * Admin access to the Oleria workspace. ### Required permissions AvaTax controls access with one security role per user. A license key acts for the whole account. | What Oleria does | AvaTax security role | | :- | :- | | Import users, roles, companies, license keys, accounting-firm links, and activity | An account-wide role. **AccountUser** is the minimum. | | Take [remediation actions](#remediation-actions) | **AccountAdmin** (or **AvaTaxOnlyAccountAdmin**). User actions also accept **AvaTaxOnlyUserAdmin**. | A license key acts for the whole account, so it can import everything listed above. If you connect with a username and password, give that user an account-wide role. Oleria refuses a user with a company role, because that user can see only part of the account. ## Get your credentials **License key (recommended)** **1. Sign in as an account administrator** Sign in to the Avalara portal for the environment you want to connect: production, or sandbox for a sandbox account. **2. Create a license key for Oleria** Go to **Settings** -> **License and API keys**, open the **License key and client secrets** tab, and select **Create license key**. Give the key a name that identifies Oleria, for example `Oleria`, and note the name exactly: you enter it in the connection form. A secondary key dedicated to Oleria can be revoked on its own without affecting your other integrations. **3. Save the key and your account ID** Avalara emails you the new license key with your account details. Avalara doesn't store the key, so save it securely. Note your AvaTax **Account ID** from the same email. The key can take a few minutes to start working. **Username and password** **1. Create a dedicated user** Create an AvaTax user for Oleria with an account-wide security role: **AccountAdmin** or **AvaTaxOnlyAccountAdmin** to use remediation actions, or **AccountUser** to import data only. **2. Allow password sign-in** If your account requires SAML single sign-on or multi-factor authentication, add the user to the sign-in exclusion list. Otherwise AvaTax refuses the password. > [!NOTE] > > AvaTax production and sandbox accounts are separate, with separate users, account IDs, and license keys. Create the credentials in the environment you want Oleria to read. The exact location of these settings can change over time. If the steps above don't match what you see, refer to Avalara's own documentation. ## Connect Avalara AvaTax to Oleria **1. Open the integration** Go to your Oleria workspace, select **Integrations** -> select **Avalara**. **2. Complete the connection form** Select **Continue** and provide the following: | Field | Notes | | :- | :- | | Environment | Required. **Production** or **Sandbox**, matching the AvaTax account. | | Authentication method | Required. **License key (recommended)** or **Username and password**. | | Account ID | Required with a license key. With a username and password, Oleria finds the account from the user. | | License key | Required with a license key. | | License key name | Optional. The exact name of the license key you entered above, as AvaTax lists it, for example `Default` or `Oleria`. Oleria uses it to recognize its own key: it never revokes that key, and it attributes activity made with the key to that key's non-human identity. Without it, Oleria refuses to revoke any license key. You can add or change it later by editing the integration. | | Username, Password | Required with a username and password. | > [!WARNING] > > Oleria can't check that **License key name** matches the key you entered. If the name is wrong, Oleria protects the wrong key, and **Disable NHI** can delete the key this integration uses. The integration then stops working, and the key can't be restored. **3. Confirm the connection** Select **Authenticate** to validate the credentials. Oleria checks that they sign in to the account, and reads the account, one user, and one company. Find the newly connected account on the **Connected** tab of your Oleria **Integrations** page. If **Authenticate** fails, check that: * The **Environment** matches the account. Production and sandbox accounts are separate. * The **Account ID** and **License key** belong to the same account. * A username-and-password user has an account-wide role, and is on the sign-in exclusion list if your account requires SAML or MFA. > [!NOTE] > > Each integration covers one AvaTax account in one environment. To connect another account, or the other environment, add a new integration. ## Verify the integration Confirm the AvaTax account appears on the **Connected** tab of your Oleria **Integrations** page with a status of **Healthy**. After the first sync completes, you can review the discovered accounts, non-human identities, secrets, roles, companies, and activity in your Oleria workspace. > [!NOTE] > > To rotate the credentials, edit the integration in Oleria, enter the new license key or password, and select **Update**. To keep the stored license key or password, leave the field empty. This works only if you don't change the **Authentication method** or, for a password, the **Username**. You can also switch the authentication method, or add or change the **License key name**. You can't change the **Environment** or **Account ID** of an existing integration, and Oleria rejects credentials that belong to a different AvaTax account. ## Remediation actions Oleria can take these actions in AvaTax. They need the **AccountAdmin** or **AvaTaxOnlyAccountAdmin** role, or a license key. The user actions also work with **AvaTaxOnlyUserAdmin**. With a username and password, Oleria checks the user's role before it runs an action. With a license key, AvaTax usually doesn't reveal the key's role, so Oleria can't check it in advance. If the key can't make the change, the action fails when it runs, and AvaTax makes no change. | Action | What it does | Revert | | :- | :- | :- | | Deactivate user | Deactivates an AvaTax user. | Reactivates the user. | | Reactivate user | Reactivates an inactive AvaTax user. | Deactivates the user again. | | Create user | Creates an AvaTax user with the **NoAccess** role, so the new user can't reach any company until you add a role. The user is inactive unless you activate it. AvaTax emails the new user an invitation to set a password. | Deletes the created user. | | Delete user | Deletes an AvaTax user. | Not supported. AvaTax can't restore a deleted user. | | Add role | Gives a user who has no role (**NoAccess**) a security role. Only account-level and company-level roles can be added. A company role needs the user to have a home company. An account-wide role clears the user's home company, because AvaTax doesn't allow both. | Removes the role again, and restores the home company if the action cleared it. | | Remove role | Sets the user's role to **NoAccess**. The user keeps their home company. | Restores the role. | | Revoke resource permission | Removes a company user's access to their home company by setting their role to **NoAccess**. The user also loses access to the home company's child companies, so they're left with no access to any company. | Restores the role. | | Disable NHI | Deletes a license key. Every integration that uses the key stops working. | Not supported. A deleted license key can't be restored. | | Remove external access | Revokes an accounting firm's link to your account. The firm can no longer see or manage your companies. | Not supported. The firm must send a new link request. | If a user, role, or firm link is already in the state an action asks for, for example a user that's already deleted or a firm link that's already revoked, the action succeeds without making a change, and there's nothing to revert. **Disable NHI** is different: if the license key no longer exists, the action fails with a not-found error. **Remove external access** also fails if the firm has no link to your account. A revert changes only what the action changed. If the target was deleted or changed again since the action ran, the revert leaves it as it is. If AvaTax doesn't answer a change, Oleria reads the target again to find out whether the change applied. If it can't tell, an action that removes access fails with a message to check AvaTax before you retry. An action that grants access succeeds and is marked unconfirmed. Oleria sends **Delete user**, **Disable NHI**, and **Remove external access** only once. If a retried **Disable NHI** fails with a not-found error, the earlier attempt may already have deleted the key. Keep these limits in mind: * **One role per user.** AvaTax users hold exactly one security role. Add role works only for a user with no role, so a user's role is never replaced by surprise. To change a role, remove it first, then add the new one. To move a user from an account-wide role to a company role, first give them a home company in AvaTax. * **Company access follows the role.** A user with an account-wide role reaches every company, so you can't revoke one company from them. Use Remove role instead. A company user reaches their home company and its child companies, so you can revoke the home company, but not one child company on its own. * Oleria won't deactivate, delete, or change the role of the user this integration signs in as. * Oleria won't deactivate, delete, or remove the role of the last active account administrator, so someone can always manage users and license keys. * Oleria won't delete the license key this integration uses. If you connected with a license key and didn't enter its name, Oleria refuses to delete any license key. * AvaTax lets you revoke accounting-firm links only from the 10th to the last day of each month. Outside that window, the action fails with AvaTax's error. ## Known limitations * **No groups.** AvaTax has no user groups. * **No multi-factor authentication status.** AvaTax doesn't expose each user's MFA status, or your account's MFA policy, through its API, so MFA reports as unavailable. * **Single sign-on is account-wide.** Oleria records whether SAML single sign-on is configured for the account. AvaTax doesn't expose its sign-in exclusion list, so Oleria can't tell which users still sign in with a password. * **No sign-in dates.** AvaTax's API doesn't report last sign-in, last activity, or last password change for users, or last use for license keys. Dormant accounts and keys can't be detected from AvaTax alone. * **License keys don't show what they authenticate.** A license key acts for the account as a whole. AvaTax doesn't list the account-level principal a key signs in as, so a license key isn't linked to an account. * **Configuration-change activity depends on your account.** The configuration-change audit export may need to be enabled for your account. If AvaTax reports that the export isn't available to your account or role, Oleria imports failed API calls only. AvaTax notes that not every update and deletion is captured in its audit log. * **Activity sync fails rather than skip recent activity.** If AvaTax refuses to return recent audit records for any other reason, the activity sync fails and retries, so the period isn't recorded as having no activity. If the activity sync keeps failing, check that the configuration-change audit export is enabled for your account, or contact support. On the first sync, Oleria skips the oldest periods that AvaTax no longer keeps. * **Very busy hours are cut.** If more than 100,000 API calls fail in one hour, Oleria imports 100,000 of them and skips the rest of that hour. * **Some configuration-change periods can be skipped.** Oleria reads configuration changes a week at a time. If the export file for a week is larger than 64 MB, Oleria skips that week's configuration changes. On the first sync, Oleria also skips a week if AvaTax fails to deliver its export after three tries. For recent activity, the sync fails and retries instead. * **No sign-in history.** Neither AvaTax audit source records successful sign-ins. * **Accounting-firm users aren't listed.** Oleria shows each linked firm as one external account. The firm's individual users live in the firm's own Avalara account. ## Contact us For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.