> ## Documentation Index
> Fetch the complete documentation index at: https://developer.trychart.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve Access Token

> In this guide, you'll exchange the authorization code for an access token.  Access tokens are required for making API requests to Chart endpoints.

Now that you have successfully [integrated Chart Connect](/implementation/connect/set-up-chart-connect) into your application's frontend and obtained an authorization code,
you will need to exchange it for an access token. Access tokens are required for making API requests to Chart's various endpoints.
In this step, you'll set up a secure server-side process to exchange the authorization code for an access token.

1. **Create a server-side “callback” endpoint**: Set up a secure server-side endpoint in your application
   to handle the exchange of authorization codes for access tokens.
   This endpoint should be accessible only by your application's backend to ensure the security of the process.
   This endpoint will receive the authorization code as a query parameter from your frontend
   and communicate with Chart's API to obtain the access token. Example: `https://example.com/api/chart/callback`.

   > You can reuse this same endpoint to support a Redirect Chart Connect flow as well.
   > Just make sure to add the `redirect_uri` to the whitelist in your Chart Developer Dashboard.

2. **Exchange the authorization code for an access token**: In your server-side code, make a POST request to the `/auth/token` endpoint.
   The request should include the following fields in the request body's JSON payload:

   * `client_id`: Your unique client ID from the Chart developer dashboard.
   * `client_secret`: Your unique client secret from the Chart developer dashboard.
   * `code`: The authorization code obtained from Chart Connect in the [Set Up Chart Connect](/implementation/connect/set-up-chart-connect).
   * `redirect_uri` (optional): If using the Redirect Chart Connect Flow, include the `redirect_uri`. Not required for the Embedded Flow.
     This is the same redirect URI you used when setting up Chart Connect. If you using Embedded Flow, do not include `redirect_uri` in the payload.

   ```shell Token exchange example theme={null}
   curl https://api.trychart.com/auth/token \
   -X POST \
   -H "Content-Type: application/json" \
   --data-raw '{
       "client_id": "<your_client_id>",
       "client_secret": "<your_client_secret>",
       "code": "<your_authorization_code>"
   }'
   ```

   **Optional Header for Async Processing**

   You can add the optional `x-chart-async: "true"` header to prevent network timeouts during long document parsing operations:

   ```shell Token exchange with async header theme={null}
   curl https://api.trychart.com/auth/token \
   -X POST \
   -H "Content-Type: application/json" \
   -H "x-chart-async: true" \
   --data-raw '{
       "client_id": "<your_client_id>",
       "client_secret": "<your_client_secret>",
       "code": "<your_authorization_code>"
   }'
   ```

   <Note>
     We recommend adding the `x-chart-async: "true"` header to avoid network timeouts when parsing takes longer than expected.
   </Note>

   <Warning>
     **Important Caveat**: When using the `x-chart-async: "true"` header, the token exchange will return immediately after pulling documents from the provider, without waiting for parsing to complete. This means there's no longer a guarantee that tax records are fully parsed when the API call ends.

     You must wait for the `taxpayer_status` to change to `COMPLETED` through webhooks before you can reliably access the parsed JSON data of the retrieved documents.
   </Warning>

3. **Handle the response**: Chart's `/auth/token` endpoint will respond with a JSON object containing an `access_token`
   if the request is successful. Parse the JSON response body and extract the `access_token`.

   ```javascript theme={null}
   {
     "taxpayer_id": "ac3a2af9-ce03-46c4-9142-81abe789c64d",
     "provider_id": "turbotax",
     "access_token": "7e965183-9332-423c-9259-3edafb332ad2"
   }
   ```

4. **Securely store the access token**: It is critical to store access tokens securely,
   as they grant access to sensitive user data. Implement a secure storage solution to store access tokens,
   treating them with the same level of security as passwords. Do not log or expose access tokens to your frontend application.
   Storing access tokens is covered in more depth in Store Tokens.

5. **Handle errors**: If the `/auth/token` endpoint returns an error, your server-side code should handle it gracefully.
   Common error scenarios include invalid or expired authorization codes, incorrect client IDs or secrets,
   or mismatched redirect URIs. Display a helpful error message to the user or retry the authentication flow as needed.

## Checkpoint + Next Step

<Check>
  After completing this step, your application will be able to exchange
  authorization codes for access tokens securely and automatically. You are
  ready to use the access token to make API requests to Chart's various
  endpoints.
</Check>