Overview
Getting Started
Widgets
Categories
Keywords
Reviews
Users
Businesses
Businesses Search
Negotiations
Messages
Requests
Help
Changelog
Terms and Policies
Thumbtack's APIs utilize the OAuth 2.0 protocol. OAuth2 is an industry-standard protocol for authorization that allows applications to access resources on behalf of a user OR on behalf of an application, both without sharing credentials.
In order to authenticate with the Thumbtack API using OAuth2, your Account Manager will provide you with:
- Client ID: A public identifier for your application.
- Client Secret: A private key known only to the application and the authorization server.
- A List of Scopes: A list of supported Scopes your Client has access to. If you require additional Scopes, kindly reach out to your Account Manager.
Our APIs use either the authorizationCode Flow or clientCredentials Flow - both of which are discussed below.
The authorizationCode Flow is used when an application needs to act on behalf of a user. This Flow involves a user logging in and granting permission to the application, namely:
- The user is redirected to Thumbtack's authorization server's Authorization URL. The user then logs in to their Thumbtack account and approves access.
- An authorization code is returned from the Authorization URL to the application.
- The application exchanges the returned authorization code (along with the Client ID, Client Secret, and Redirect URL) to Thumbtack's authorization server's Token URL.
- An access_token is returned from the Token URL to the application, along with a refresh_token.
As part of the authorizationCode Flow, there are two important URLs to be aware of (which are Environment specific - see more at Environments):
- Authorization URL: https://auth.thumbtack.com/oauth2/auth
This is where the user is redirected to authenticate and grant consent to the application. It initiates the flow by allowing the user to log in to Thumbtack and to approve access to their resources. - Token URL: https://auth.thumbtack.com/oauth2/token
After the user grants consent, the application receives an authorization code. The application then exchanges this code for an access_token by making a secure server-to-server request to the token URL. This ensures that sensitive tokens are not exposed to the user's browser.
The clientCredentials Flow is used when when an application needs to access resources on its own behalf (no user interaction). This Flow involves the application directly requesting an access_token from Thumbtack's authorization server using its Client ID and Client Secret, namely:
- The application sends its Client ID and Client Secret to the Token URL
- An access_token is returned from the Token URL to the application.
As part of the clientCredentials Flow, there is an important URL to be aware of (which is Environment specific - see more at Environments):
- Token URL: https://auth.thumbtack.com/oauth2/token
This is the endpoint where the application exchanges its client ID and secret for an access_token This token is then used to authenticate API requests on behalf of the application itself.
As part of either Authentication Flow, you will be required to specify which Scopes the client application is requesting (on behalf of a user or of the application itself). Scopes specify what resources or actions the client can access. They ensure that the client only gets the permissions it needs, following the principle of least privilege.
Scopes are passed to each Flow as follows, with multiple Scopes separated by spaces:
- authorizationCode Flow: The client includes the scope parameter in the request to the Authorization URL.
- clientCredentials Flow: The client includes the scope parameter in the request to the Token URL.
Per-route Scopes are documented in the API Reference. Expanding any of the AUTHORIZATIONS sections for any endpoint will list the required Scope(s), along with a full list of supported Scopes for each Authentication Flow. Note that if multiple scopes are listed, only one is required.
offline_access: The offline_access Scope pertains only to the authorizationCode Flow and is crucial for obtaining a new access_token from Thumbtack's authorization server after the access_token expires. Once the access_token expires, the refresh_token is exchanged with Thumbtack's authorization server to allow the client application to obtain a new access_token without requiring the user to log in again, enabling long-lived access to resources.
If you wish to access the details of the user that is authenticating, you can utilize OpenID Connect Scopes, which will include an id_token (a JWT Token) in the response. In order to do so, the relevant Scopes are:
- openid: Required. Returns the sub claim (the User's ID) in addition to the iss, aud, exp, iat, and at_hash claims.
- profile: Optional. Will include the name, given_name (First Name), family_name (Last Name), picture, and zoneinfo (Timezone) claims.
- email: Optional. Will return the email and email_verified claims.
- phone: Optional. Will return the phone_number claim.
A User's ID, email, phone number, first name, and last name can all be alternatively be obtained via the Users API.
On Thumbtack's side, we classify Partners as Supply-side (i.e. Integrating Thumbtack tightly into their Platform, such as CRMs) or Demand-side (i.e. Presenting Thumbtack Data on their Platform). When we provide you your Client Information, you will also be provided a list of Scopes provisioned to your Client. The Scopes will consist of either purely demand:: or purely supply:: prefixed scopes - there will never be a mix. From here, it will be clear whether your Client is a Supply-side or Demand-side Client.
In addition to the Client ID, Client Secret, and Scopes, there are a few other parameters you must include, depending on the Authorization Flow.
- redirect_uri: A string that represents the URL Thumbtack redirects to after authorization is completed.
- response_type: Must be code. Indicates that the client expects an authorization code in the response.
- state: A string used to maintain state between the client and Thumbtack's authorization server and is appended to the redirect_uri upon successful user authorization. The client includes a unique state value in the authorization request. Thumbtack's authorization server includes the same state value in the response. The client verifies the returned state to ensure the response is valid.
- audience: Must be set to urn:partner-api. audience is used in the Authorization request.
- audience: Must be set to urn:partner-api. audience is used in the Token request.
We strongly recommend utilizing an OAuth2 library created for whatever language you are utilizing. OAuth has compiled popular OAuth2 libraries for several languages.
If you would rather roll your own implementation, continue reading below. Note that the below URLs are Environment specific - see more at Environments.
NOTE: The URL parameters for the all API calls must be URL encoded.
GET https://auth.thumbtack.com/oauth2/auth?response_type=code&client_id={{client ID}}&redirect_uri={{redirect URI}}&scope={{list of Scopes separated by a + sign}}&state={{state}}&audience={{audience}} HTTP/2
After confirming the connection, Thumbtack will redirect the User to the provided Redirect URI with the Authorization Code included the URL. This Authorization Code will expire in five minutes.
The redirect URL will look like:
{{redirect URI}}/?code={{authorization code}}&state={{state}}
The redirect URL will look like:
{{redirect URI}}/?code={{authorization code}}&state={{state}}
Issue the following request:
POST https://auth.thumbtack.com/oauth2/token HTTP/2authorization: Basic {{base64 encoded clientID:clientSecret}}content-type: application/x-www-form-urlencodedgrant_type=authorization_code&code={{authorization code}}&redirect_uri={{redirect URI}}
Which would return an object such as:
{"access_token": "{{access token}}","expires_in": 3600,"refresh_token": "{{refresh token}}","scope": "{{space separated list of Scopes}}","token_type": "bearer"}
When an access_token expires, you will need to refresh the token by making a call to the Token URL. In making the below call, you would include the refresh_token returned from the initial call to fetch an access_token. The returned response will include a new access_token and refresh_token.
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 POST 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 to retry fetching 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.
POST https://auth.thumbtack.com/oauth2/token HTTP/2authorization: Basic {{base64 encoded clientID:clientSecret}}content-type: application/x-www-form-urlencodedgrant_type=refresh_token&token_type=REFRESH&refresh_token={{refresh token}}
Which would return an object such as:
{"access_token": "{{new access token}}","expires_in": 3600,"refresh_token": "{{new refresh token}}","token_type": "bearer"}
When submitting calls to any API endpoints, you will now include the access_token in the Authorization Header:
authorization: Bearer {{access_token}}
If you choose to disconnect an integration between Thumbtack and a User on your Platform, you must call our disconnect endpoint. The disconnect endpoint revokes said User's OAuth refresh and access_tokens, along with disconnecting any active webhooks your integration may have created for the User.
Issue the following request:
POST https://auth.thumbtack.com/oauth2/token HTTP/2authorization: Basic {{base64 encoded clientID:clientSecret}}content-type: application/x-www-form-urlencodedgrant_type=client_credentials&scope={{list of Scopes separated by a + sign}}&audience={{audience}}
Which would return an object such as:
{"access_token": "{{access_token}}","expires_in": 3600,"scope": "{{space separated list of Scopes}}","token_type": "bearer"}
When submitting calls to any API endpoints, you will now include the access_token in the Authorization Header:
authorization: Bearer {{access_token}}
If you receive a 401 Unauthorized response when hitting the /oauth2/token endpoint, your body may look like:
{"error": "invalid_client","error_description": "Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method)."}
This is due to a Client not being found in the associated Environment's OAuth Authorization Server. To resolve this, ensure that you are using the correct OAuth Authorization Server, clientID, and clientSecret for the desired Environment.