# Company-level two-factor authentication

Source: https://developer.avalara.com/products/returns/integration-guides/managed-returns/rty9684532390671/

Guide: Avalara Managed Returns API (U.S. and Canada)

# Company-level two-factor authentication

Learn how company-level two-factor authentication (2FA) works and how Avalara routes security codes during tax authority onboarding.

Some state tax authorities require two-factor authentication (2FA) or multi-factor authentication (MFA) to access their online portals. When a tax authority requires 2FA, it sends security verification codes to a designated email address during credential validation.

Avalara manages 2FA at the company level, instead of at the individual tax authority level. This approach helps you manage access securely across multiple jurisdictions.

## How company 2FA works

-   **Centralized company alias:** Each company has exactly 1 Avalara alias email address assigned by Avalara. This alias is shared across all tax authorities that the company uses for onboarding.
-   **Automatic alias provisioning:** When you query the company two-factor settings, Avalara automatically generates the alias address if the company does not already have one.
-   **Email forwarding:** Each company can have only 1 forwarding email address. When a tax authority sends a security verification code to the company alias address, the alias automatically forwards the message to the customer notification email configured for that company.
-   **Shared configuration:** Because 2FA settings apply at the company level, updating the forwarding email changes the destination address for all return onboarding activities and tax authorities associated with that company.

You can manage two-factor authentication with these operations:

-   **Query company two-factor settings:** Retrieve the company alias address and the current forwarding email by using the companies query. For details, see [Query company two-factor settings](/managed-returns/mse4585278200914/ "Retrieve a company's 2-factor authentication (2FA) forwarding alias and notification email settings with the companies GraphQL query.").
-   **Update company two-factor alias:** Change the email address that receives forwarded security verification codes by using the `updateCompanyTwoFactorAlias` mutation. For details, see [Update company two-factor alias](/managed-returns/asq2206617581230/ "Update the email address that a company two-factor authentication (2FA) alias forwards to by using the updateCompanyTwoFactorAlias GraphQL mutation.").
-   **Query received two-factor security codes:** Review the history of verification emails and security codes received by the company alias by using the companies query. For details, see [Query received two-factor security codes](/managed-returns/eqz5010147963677/ "Retrieve 2-factor authentication, 2FA, emails, and security verification codes for a company by using the companies GraphQL query.").

For tax authority onboarding that requires 2FA, where `isTwoFactorAuthRequired` is true, use this general workflow:

1.  Retrieve the company alias. Call the companies query with the `twoFactorSettings` field to get the company alias address and current forwarding email.
2.  Enter the alias on the authority portal. If the state portal requires it, add the Avalara alias email address as the authorized contact or sign-in email.
3.  Update the forwarding email, if needed. If the customer wants to receive verification codes at a different email address, call the `updateCompanyTwoFactorAlias` mutation.
4.  Verify received security codes, if needed. Query the `codeDetails` field on the companies query to view incoming verification emails and extracted security codes.