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 authentication lifecycle

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.

Authorizing data sharing

Step 1: Get credentials and staging environment access

To get developer credentials with Thumbtack, contact us via the Request Access button on your landing page. In addition to the credentials, you'll be given access to our staging environment, 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.

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

Client ID / consumer key
Client secret / consumer secret

Step 2: Connect a Thumbtack account with a partner service

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:

GET https://auth.thumbtack.com/oauth2/auth?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URL>&response_type=code&scope=<SCOPE>

Before you start

We strongly encourage you to use an OAuth library for your tech stack where possible, or alternatively the generated OAuth APIs via our OpenAPI spec if your stack supports the security extension.

Below documents the information needed for a both a manual implementation alongside one utilizing a library.

Note for manual OAuth implementation

The URL parameters for the all API calls must be URL encoded. For example, with the following API, if you had a parameter "lorem ipsum", it would be encoded as below

https://thumbtack.com/example-api/?your_param=<PARAMETER>

https://thumbtack.com/example-api/?your_param=lorem%20ipsum

OAuth connection URL Parameters

Parameter Name	Type	Description
client_id	string	This is a consumer key provided by Thumbtack.
scope	string	Authorization scopes allow access to specific information from Thumbtack.
redirect_uri	string	Thumbtack redirects the pro to this URL after they complete authorization.
response_type	string	This must contain string code as a response type.
state	string	The client inserts state information that will be appended to the redirect_uri upon successful user authorization. If state is not required by the client, send a random 10 character string.

Authorization scopes

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.

Step 3: Obtain an authorization code

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>

Note

The authorization code will expire in 5 minutes

Step 4: Request an access token

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.

Request endpoint

POST https://auth.thumbtack.com/oauth2/token

Request header

Authorization: Basic <B64-encoded_oauth_credentials>

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.

Access token request parameters

Parameter	Type	Description
grant_type	string	This must contain string authorization_code as a grant type.
code	string	The authorization code is returned to the redirect_url in the step-3.
redirect_uri	string	Thumbtack redirects to this URL after they complete authorization.

Access token response parameters

Parameter	Type	Description
access_token	string	The access token issued by the authorization server.
token_type	string	The type of token issued. Must return bearer as a token type.
expires_in	number	The access token lifetime in seconds. The default expiry is 3600 seconds (1 hour).
refresh_token	string	The refresh token issued by the authorization server.

Note

Access Token expiry time - 1 hour

Refresh Token expiry time - 720 hours

Sample response:

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

Refreshing connections

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.

Request endpoint

POST https://auth.thumbtack.com/oauth2/token

Request header

Authorization: Basic <B64-encoded_oauth_credentials>

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.

Expected Request Params

Parameter	Type	Description	Required
grant_type	string	This must contain string refresh_token as a grant type.
refresh_token	string	The refresh token value that you received along with the access token in step-4.
token_type	string	This must contain string REFRESH as a token type.

Expected Response Params

Parameter	Type	Description	Required
access_token	string	The access token issued by the authorization server.
token_type	string	The type of token issued. Must return bearer as a token type.
expires_in	number	The access token lifetime in seconds. The default expiry is 3600 seconds (1 hour).
refresh_token	string	The refresh token issued by the authorization server.

Error handling with grace period

We have implemented a grace period in the OAuth refresh token flow to handle network errors, timeout errors, and similar issues. If you receive null in the response to the https://auth.thumbtack.com/oauth2/token API at the time of refreshing the token, we encourage your partner service to implement the retry logic on their side. This will call the https://auth.thumbtack.com/oauth2/token API with the same refresh token to get the valid response. The grace period time is 10 seconds.

Disconnecting from the OAuth flow disconnecting active webhooks

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 the active webhooks for the business in question. See the API spec for more information.