# Authentication in TaxDocs

Source: https://developer.avalara.com/tax-docs-en/authentication/how_do_i_authenticate_to_my_taxdocs_account/

# Authentication in TaxDocs

This section describes the necessary steps to create a token and how to authenticate it in our API.

Authentication supports OAuth 2.0, which means that an access token is received to allow access to the application for each call with the credentials obtained. This "Access Token" is valid for a specific period of time, and it is necessary to send the credentials again to obtain new access once it expires.

It is possible to renew the "Access Token", or to send the credentials on each new call, but the second way is usually indicated only in cases of an unsafe environment, such as GUIs.

### STEP 1: Create an API access token through the Avalara Portal:

TASK

RESULT

The entire process for creating the token and the credentials required to access an access token are made through the Avalara Portal.

Access the portal at the following URL: [https://portal.sandbox.avalarabrasil.com.br/Login](https://portal.sandbox.avalarabrasil.com.br/Login)

`Access to Avalara portal       https://portal.sandbox.avalarabrasil.com.br/Login`

Click`configurações` (configuration), and then click`tokens de assinatura` (signature tokens).

A message displays showing `+ novo token de assinatura` (new signature token).

Select the`+ novo token de assinatura` (new signature token) option.

A basic info box (`informações básicas`) for the Signature token opens.

Generate a new token:

1.  Choose a name in the name field (`nome`).
2.  Select a start date in the start date field`(Data início DD/MM/YYYY)`.
3.  Select an end date in the end date field`(Data fim DD/MM/YYYY)`.
4.  Press **Save**.`      `

`Generates a new token!                  `

A new window opens with the token information`(informações do token)`.

-   On the signature field `(assinatura)`, the value that should be sent in the tag "`client_id`" appears.
-   On the secret token field `(segredo do token)`, the value that should be sent in the tag  "`client_secret`" appears

Attention: Ensure that you save the token in a safe place before you conclude the process. It won't be possible to retrieve it again.

1.  Press the "yes, I've saved the token secret in a safe place" `(sim, guardei o segredo do token em segurança)` button.
2.  Click (`fechar`) to close.

`The signature and token secret values are shown`

**Advice:** Following best practices, we recommend that each application connecting to our solution uses a separate Access Token.

### STEP 2: Getting an access token

Now that you created the necessary credentials inside our Portal, you just need to call our API to get an access token.

**Mandatory fields**

**Attributes**

**Description**

Mandatory

grant\_type

To request an initial “`Access Token`”, you must send the “`client_credentials`” value.

Mandatory

client\_id

This is equivalent value to “`subscription ID`”.

Mandatory

client\_secret

The unique token (`secret`) provided during token creation on the Avalara Portal.

Suggested

disableTokenRefresh

This property indicates whether or not the session requester wants to obtain the “`RefreshToken`” to renew the session every “X” minutes.

If the applicant chooses to keep the session active until the expiration in “X” hours, without periodic renewal, then a fixed amount must be sent as “`true`” and the “`RefreshToken`” **WILL NOT BE RECEIVED**.

**Advice: If this property is sent in the initial request as "false", the refresh token step must be executed.**

**Request Model:**

POST: [https://api-gateway.sandbox.avalarabrasil.com.br/oauth/oauth/token](https://api-gateway.sandbox.avalarabrasil.com.br/oauth/swagger/index.html)

```
{ "grant_type": "client_credentials", "client_id": "", "client_secret": "", "disableTokenRefresh": true}
```

**Advice:** This process must be repeated until the session expires. This expiration information can be verified in the body's response tag named: "`expires_in_session`", and once it expires, you must start the process from the beginning. 

**Refresh token**

As mentioned, when`"disableTokenRefresh"=false`, the value of the "`refresh_token`" received in the return of the initial request must be stored in order to later use this stored value for a new request for a signature token, without the need to send the credentials again.

Below is an example of how to send the session`refresh_token`:

POST: [https://api-gateway.sandbox.avalarabrasil.com.br/oauth/oauth/token](https://api-gateway.sandbox.avalarabrasil.com.br/oauth/swagger/index.html)

```
{ "grant_type": "refresh_token", "refresh_token": "{{refresh_token}}",}
```

[Previous](/tax-docs-en/authentication/how_do_i_get_access_to_sandbox)

[Next](/tax-docs-en/authentication/ping_the_server)