# Grant authority access and trigger extraction

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

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

# Grant authority access and trigger extraction

Submit portal credentials for a tax authority, validate credentials and 2-factor authentication, and start background return extraction by using the `grantAuthorityAccess` GraphQL mutation.

The `grantAuthorityAccess` mutation submits a company's portal credentials for a tax authority, validates the sign-in and 2FA or MFA check against the live portal, and, when the credentials are accepted, starts a background extraction task that creates pending filing requests.

Key considerations:

-   **Validation duration**: The mutation waits for live portal sign-in and 2FA validation, which can take up to 4 minutes. Configure your client timeout accordingly.

-   **Authority matching**: The authority is identified by name. The value must match the name returned by the authorities query. Case and surrounding spaces are ignored.

-   **Existing access**: If access is already granted for the authority, credentials are still validated, but no duplicate extraction starts.

-   **Credential privacy**: The portal password is sent directly to the tax authority and is never returned in an API response.

## View request

```
mutation GrantAuthorityAccess($input: GrantAuthorityAccessInput!) {
  grantAuthorityAccess(input: $input) {
    jobId
    submissionKey
    validationStatus
    securityStatus
    failureReason
    syncTriggered
    tasks {
      taskId
      formCode
      status
      message
      dateCreated
      dateCompleted
      filingRequestIds
      generatedTaxFormCodes
    }
  }
}
```

**Input variables**:

```
{
  "input": {
    "companyId": "1234567",
    "country": "US",
    "region": "AL",
    "name": "Alabama Department of Revenue",
    "authMechanism": "CREDENTIAL_SCRAPE",
    "credentials": {
      "username": "your-portal-username",
      "password": "your-portal-password"
    },
    "triggerSync": true
  }
}
```

Table 1. Input variable details

Input field

Type

Description

`companyId`

`ID!`

The company being onboarded.

`country`

`String!`

The 2-character ISO 3166 country code.

`region`

`String`

The 2-character or 3-character ISO 3166 region or state code.

`name`

`String!`

The authority name from `name` on `authorities`. It is matched against the authority's DoR name, ignoring case and surrounding spaces.

`authMechanism`

`AuthorityAuthMechanism!`

Use `CREDENTIAL_SCRAPE`, which requires a username and password.

`credentials.username`

`String`

The username for the authority portal.

`credentials.password`

`String`

The password for the authority portal. It’s sent to the authority and is never returned.

`triggerSync`

`Boolean`

Whether to start extraction after the credentials are accepted. The default is `true`.

To change where 2FA emails are forwarded, use `updateCompanyTwoFactorAlias`.

## View response

Credentials accepted and extraction started:

```
{
  "data": {
    "grantAuthorityAccess": {
      "jobId": "100001",
      "submissionKey": "a1b2c3d4-0000-4000-8000-000000000001-000001",
      "validationStatus": "SUCCESS",
      "securityStatus": "SUCCESS",
      "failureReason": null,
      "syncTriggered": true,
      "tasks": [
        {
          "taskId": "aaaaaaaa-0000-4000-8000-000000000001",
          "formCode": "USAL2100",
          "status": "InProgress",
          "message": null,
          "dateCreated": "2026-01-15T09:13:30.9832215",
          "dateCompleted": null,
          "filingRequestIds": []
          “generatedTaxFormCodes”: []
        }
      ]
    }
  }
}
```

The authority already has access. The credentials are valid, but no extraction starts:

```
{
  "data": {
    "grantAuthorityAccess": {
      "jobId": "100001",
      "submissionKey": "a1b2c3d4-0000-4000-8000-000000000001-000001",
      "validationStatus": "SUCCESS",
      "securityStatus": "SUCCESS",
      "failureReason": null,
      "syncTriggered": false,
      "tasks": null
    }
  }
}
```

If validation fails, show the `failureReason` to the user and prompt for updated credentials:

```
{
  "data": {
    "grantAuthorityAccess": {
      "jobId": "100002",
      "submissionKey": "a1b2c3d4-0000-4000-8000-000000000002-000002",
      "validationStatus": "FAILED",
      "securityStatus": "CANNOT_VALIDATE",
      "failureReason": "CREDENTIALS_REJECTED",
      "syncTriggered": false,
      "tasks": null
    }
  }
}
```

**Response field descriptions**:

Response field

Description

`jobId`

Identifies this attempt. Keep it to recover the saved account with `savedAuthorityAccounts` or retry with `resumeAuthorityAccess`.

`submissionKey`

An opaque key for this submission.

`validationStatus`

The result of the portal sign-in, `SUCCESS`, `FAILED`, or `CANNOT_VALIDATE`.

`securityStatus`

The result of the 2-factor or multi-factor authentication check, with the same values.

`failureReason`

Why validation didn’t succeed. `null` on success.

`syncTriggered`

`true` only when extraction actually started. This value doesn’t echo `triggerSync`.

`tasks`

The extraction tasks that started. `null` when none started.

Failure reason values:

Value

Meaning

`CREDENTIALS_REJECTED`

The authority rejected the username or password.

`TWO_FACTOR_FAILED`

The sign-in worked, but the 2FA or MFA authentication check failed.

`TIMEOUT`

The authority didn’t respond in time.

`SYSTEM_FAILURE`

A system failure stopped validation.

`triggerSync` and `syncTriggered` are different. With `triggerSync: true`, extraction starts only if the credentials are accepted and access isn’t already granted for the authority. With `triggerSync: false`, the call only validates the credentials.

## Next step

To monitor the background extraction tasks returned in the tasks array, see [Monitor extraction task status](/managed-returns/fcy1877890471345/ "Check the status of 1 or more background return extraction tasks with the taskStatus GraphQL query.").