Redirect to Finch Connect

In this method of integrating Finch Connect, your application redirects your user's browser to Finch Connect hosted by Finch on https://connect.tryfinch.com. The authorization flow will consist of four steps:

Open Finch Connect - Your application redirects your user's browser to Finch Connect to initiate the authorization flow.
Obtain consent - Finch Connect prompts your user to log in to their employment system and grant your application access to the permissions you are requesting for.
Retrieve the authorization code - If your user successfully connects and grants your application access to their system, Finch Connect will redirect their browser to a specified redirect_uri with a short-lived authorization code.
Exchange the code for an access token - Before sending API requests, your application will exchange the short-lived code for a long-lived access_token that represents your application's access to your user's employment system.

Open Finch Connect

When your application needs access to your user's employment system redirect them to Finch Connect.

Construct the Finch Connect redirect with the parameters below:

Parameter	Required	Description
`client_id`	true	Your `client_id`, a unique identifier for your application.
`redirect_uri`	true	The URI your user is redirected to after successfully granting your application access to their system. This value must match one of your application's configured redirect URIs. Read more here.
`category`	false	The category of integrations your applications would like to expose. Options: `hris` and `ats`. If no category is provided, defaults to `hris`.
`products`	true	A space-separated list of permissions your application is requesting access to. See here for a list of valid permissions.
`state`	false	An optional value included as a query parameter in the `redirect_uri` back to your application. This value is often used to identify a user and/or prevent cross-site request forgery.
`payroll_provider`	false	An optional parameter that allows you to bypass the provider selection screen by providing a valid provider `id`. Read here for more information.
`sandbox`	false	An optional value that allows users to switch on the sandbox mode to login with fake credentials and test applications against mock data. For more information, read our Testing Development Guide.
`manual`	false	An optional value which when set to true displays both Automated API and Assisted API providers on the selection screen.

Connect displays the permissions your application is requesting access to. If your user approves, they are asked to select their provider and are then prompted to log in to their account.

Retrieve the authorization code

Connect sends the end user’s approval or denial back to your application’s server via the specified redirect URI.

If the user grants your application access and successfully connects their account, they are redirected to the specified redirect_uri with the query parameters below. You will have to ensure the listener at the redirect_uri, which can be either on the front or back-end, can parse the code out of the uri.

Parameter	Required	Description
`code`	true	An authorization code that will be used to obtain an `access_token` in the following step. The authorization `code` expires in 10 minutes.
`state`	false	If the redirect to Finch Connect contains a `state` parameter, the same parameter will be returned here.

Exchange the code for an access token

To interact with the Finch API, you will need to exchange your short-lived authorization code for a long-lived access_token.

Request

Note

The exchange step should always take place in your back-end to ensure your client_secret and access_token are never publicly exposed.

Header	Description
`Content-Type`	Must be set to `application/json`, matching the format of the request body.

Response

Note

A Finch access_token is long-living, i.e. it does not expire.

Parameter	Description
`access_token`	The `access_token` used to make requests to the Finch API. It has does not expire and should be stored securely in your database.

Next steps