Authenticating and authorizing with the Thumbtack API using OAuth 2.0

Thumbtack’s leads and messaging APIs expose a real-time webhook-based API to integrate Thumbtack into your customer acquisition workflows. This guide explains the authorization and authentication workflow lifecycle, from connection to disconnection.

Thumbtack’s API’s implement the OAuth 2.0 protocol, specifically using the authorization code flow. A Thumbtack pro, once initiating the flow from your product, will log in to Thumbtack, authorize Thumbtack to share their data with you, and then redirect back to a URL of your choosing.

The lifecycle consists of: 1) authorization of data sharing, 2) refreshing connections, and 3) disconnection. Implementation of all three is required in order to complete the integration.

To get developer credentials with Thumbtack, contact us via the Request Access button at the top right of the page.  We will create OAuth credentials for you in the production environment. Should you require access to staging you must ask for this as well and you must provide a separate redirect uri for your development or staging environment (multiple redirect uris are supported for any environment should you require them). This can be public or private as the redirect is performed using the user's browser. You will be given additional OAuth credentials that will be used for our staging environment and you will be given login credentials to access our staging environment as an actual user.

In order to implement Thumbtack’s APIs, you’ll need OAuth credentials. They consist of the following pairs for both your staging and production environments:

Our staging environment is where you can create your own data and interact with the Thumbtack product as if you were a customer and a pro, allowing full end to end testing. You will need to use the staging url and the credentials we provide you which consist of:

The authorization flow for staging uses a different domain which consists of:

https://staging-auth.thumbtack.com/

The api for staging also uses a different domain which consists of:

https://staging-api.thumbtack.com/

In order for a Thumbtack pro’s data to be shared by Thumbtack with your integrated partner service, the pro must authorize the connection via the OAuth flow. You will direct the Thumbtack OAuth authorization flow using the following URL:

Partners will have to pass the relevant scope with which they want to integrate. Partners can pass multiple scopes if they want to integrate with multiple Thumbtack endpoints. The access token issued will be limited to the scopes granted. The documentation for each API will state the scopes required under its Authorizations section.

After confirming the connection, Thumbtack redirects the pro to a redirect URL with the authorization code in the URL. The redirect URL will look like this:
<REDIRECT_URL>/?code=<AUTHORIZATION_CODE>&state=<STATE>

Once the pro authorizes access, they're redirected back to the URL with the authorization code. This API will use an authorization code from the request return access token and refresh token in the response.

The Authorization: Basic authorization header is generated through a Base64 encoding of <client_id>:<client_secret>. You can use https://www.base64encode.org/ to see how headers should be encoded. The request parameters below are passed in as the body not as query parameters.

Sample response:

{
   "access_token": "1.eyJCdXNpbmVzc1BLIjozODgwMDYwNjczNTExNTA1OTUsIkNsaWVudElEIjoiVEhVTUJUQUNLIElOVEVSTkFMIiwiU2NvcGUiOlsibWVzc2FnZXMiXSwiRXhwaXJlc0F0IjoiMjAyMS0xMC0xNFQwMjo1OToyOS44MjIwMDU2ODhaIiwiU3JjQXV0aENvZGUiOiIwNjcwODgwODI0M2QyOTYxN2E1OTc4ZmZjNmQ4OGRkY2UzYjBjNDQyOThmYzFjMTQ5YWZiZjRjODk5NmZiOTI0MjdhZTQxZTQ2NDliOTM0Y2E0OTU5OTFiNzg1MmI4NTUifQ.qJDfeuYfdFZCSVQmBUgr_kDoZeeEUD4y4oVTVMEc4EQ",
   "expires_in": 3600,
   "refresh_token": "_s3cnwGAb5VgBt-CmYFSOw",
   "scope": "offline_access",
   "token_type": "bearer"
}

When an access token expires, you're required to use the API below with the refresh token, which has a long lifetime to obtain a new access token and refresh token pair. In order to receive a refresh token you must include the offline_access scope when initializing the OAuth flow.

The Authorization: Basic authorization header is generated through a Base64 encoding of <client_id>:<client_secret>. You can use https://www.base64encode.org/ to see how headers should be encoded. The request parameters below are passed in as the body not as query parameters.

We have implemented a 60 second grace period in the OAuth refresh token flow to handle network errors, timeout errors, and similar issues. If an error occurs when calling https://auth.thumbtack.com/oauth2/token when trying to use a refresh token, we encourage you to implement retry logic that uses the same refresh token. This will call the https://auth.thumbtack.com/oauth2/token endpoint with that same refresh token to get a new access and refresh token pair. After 60 seconds from the initial use, the refresh token is marked as invalid and can no longer be utilized.

If you choose to disconnect an integration between Thumbtack and a partner service, you're required to call our disconnect endpoint. The disconnect endpoint revokes your OAuth refresh and access tokens. It also disconnects any active webhooks your integration has created for the user in question. See the API spec for more information.