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 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.
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)
- Username and password
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.
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:
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.
- 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.
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.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.
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.