Overview
Getting Started
Widgets
Categories
Keywords
Reviews
Users
Businesses
Businesses Search
Negotiations
Messages
Requests
Help
Changelog
Terms and Policies
Thumbtack's APIs utilize and strictly adhere to 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, you will be provided 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 us.
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.
As part of authorizationCode Flows, Clients can request additional details pertaining to the user that is authenticating by utilizing OpenID Connect Scopes. OpenID Connect Scopes are only supported if your Client has been granted access to request any of the below Scopes. These additional user details are included in an id_token (a JWT Token) alongside the access_token that is returned from the Token URL.
- 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.
Note that 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 (at least 8 characters long) 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 and prevent CSRF.
- 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.
Once you have decided which Environment you wish to use, along with the requested Scope(s) and any additional Parameters, you are now ready to request an access_token!
In order to do this, you need to utilize an OAuth2 library in the coding language you are using. OAuth has compiled popular OAuth2 libraries for several languages.