Retrieve Access Token

Now that you have successfully integrated Finch 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 Finch’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 Finch’s API to obtain the access token. Example: https://example.com/api/finch/callback.

   You can reuse this same endpoint to support a Redirect Finch Connect flow as well. Just make sure to add the redirect_uri to the whitelist in your Finch 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 Finch developer dashboard.
   • client_secret: Your unique client secret from the Finch developer dashboard.
   • code: The authorization code obtained from Finch Connect in the Set Up Finch Connect.
   • redirect_uri (optional): If using the Redirect Finch Connect Flow, include the redirect_uri. This is the same redirect URI you used when setting up Finch Connect. If you using Embedded Flow, do not include redirect_uri in the payload.
   Token exchange example

   curl https://api.tryfinch.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>",
   }'
   

3. Handle the response: Finch’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.

   {
     "company_id": "4ab15e51-11ad-49f4-acae-f343b7794375",
     "account_id": "ac3a2af9-ce03-46c4-9142-81abe789c64d",
     "connection_id": "6dab009c-77c8-43d9-8f81-e093f7c65bc1",
     "provider_id": "gusto",
     "products": ["directory", "employment", "individual"],
     "client_type": "production",
     "connection_type": "provider",
     "access_token": "7e965183-9332-423c-9259-3edafb332ad2",
     "customer_id": "1234567890",
     "token_type": "bearer"
   }
   

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

​

Learn more

• Store Tokens
• Mitigate Errors