Partner Platform

Request Access

Overview

Getting Started

Widgets

Categories

Keywords

Reviews

Users

Businesses

Businesses Search

Negotiations

Messages

Requests

Help

Changelog

Terms and Policies

Authentication

Learn how to authenticate to the Thumbtack APIs.

OAuth2

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.
Note: We do not explicitly support manual OAuth implementations because of the fragility they introduce. Partners attempting this are on their own. Instead, you should always use an OAuth2 library supported by your programming language.

Getting Started

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 (see Scopes section). If you require additional Scopes, kindly reach out to us.

OAuth2 Authentication Flows

Our APIs use either the authorizationCode Flow or clientCredentials Flow - both of which are discussed below.

1. Authorization Code Flow (User Context)

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. This access_token expires in 3600 seconds (1 hour).
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.

2. Client Credentials Flow (Application Context)

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. This access_token expires in 3600 seconds (1 hour).
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.

Required Parameters in Each Flow

In addition to the Client ID and Client Secret, there are a few other required parameters you must include, depending on the Authentication Flow.

1. Authorization Code Flow

In /oauth2/auth call,
  • 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.
  • scope: Must be a space-delimited list of Scopes you wish to request. See the OAuth2 Scopes section for more details.

2. Client Credentials Flow

In /oauth2/token call,
  • audience: Must be set to urn:partner-api. audience is used in the Token request.
  • scope: Must be a space-delimited list of Scopes you wish to request. See the OAuth2 Scopes section for more details.

OAuth2 Scopes

Scopes determine what resources and actions your client application can access. They enforce the principle of least privilege by ensuring the client only has permissions it truly needs.
Scopes are required for both flows:
  • In the Authorization Code Flow: included in the request to the Authorization URL.
  • In the Client Credentials Flow: included in the request to the Token URL.

Which Scope(s) Do I Need?

  • Each API route specifies its required scope in the API Reference.
  • Expanding the AUTHORIZATIONS section of any endpoint will list the Required Scopes.
  • If multiple required scopes are listed, only one is required.

Offline Access Scope: Refreshable Access

The offline_access scope applies only to the Authorization Code Flow. When it is included in the scope list, Thumbtack’s authorization server will issue a refresh_token alongside the access_token. Once the access_token expires (after one hour), the refresh_token can be exchanged with Thumbtack’s authorization server to obtain a new access_token without requiring the user to log in again. This enables long-lived access for client applications.
A refresh_token itself is valid for up to 6 months. Tokens can become invalid due to inactivity (expiring after 6 months), if they are manually revoked, or if they are exchanged for a new access token. To maintain long-term access, each time you exchange a refresh token for a new access token, a new refresh token is also returned—resetting the expiration window to another 6 months.

OpenID Connect Scopes: Additional User Identity

When using the Authorization Code Flow, you may also request OpenID Connect scopes. These return additional user identity details in an id_token (JWT) alongside the access_token. For more details, see: OpenID Connect Scopes.
Scope options:
  • openid (required): always returns sub (User ID), plus standard claims (iss, aud, exp, iat, at_hash).
  • profile (optional): user’s name, given_name, family_name, picture, zoneinfo.
  • email (optional): user’s email, email_verified.
  • phone (optional): user’s phone_number.
Note: User ID, email, phone number, first name, and last name can also be obtained via the Users API.

Supply vs. Demand Scopes

Thumbtack classifies partners into two categories:
  • Supply-side: deep integrations into platforms like CRMs.
  • Demand-side: presenting Thumbtack data externally.
When we provision your client credentials, your scope list will include only one of the following prefixes:
  • supply::
  • demand::
From here, it will be clear whether your Client is a Supply-side or Demand-side Client.

Putting Everything Together

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.

Last Updated: Sep 18th, 2025

On this page