Overview
Authentication is a critical component of vendor integrations, ensuring secure and reliable communication between ServiceTitan and suppliers system. When integrating with suppliers, there are two key points where authentication is configured: the Supplier (or Endpoint) Configuration and the Credentials Management stages. These configurations ensure secure and efficient communication with supplier APIs by defining the authentication method and the specific credentials required.
Who uses this feature
Supply Chain partners, vendors, suppliers
Applies to all business types
What you need to get started
Before getting started, ensure you have the following prerequisites ready:
Login Credentials: Get access to the ServiceTitan Integration API Portal.
Postman Setup: Create an account on the Postman site and download the ServiceTitan Postman collection to test API requests and configurations.
Architecture Overview: Familiarize yourself with ServiceTitan's architecture, generic endpoints and the supply chain system to understand how it works for your customers.
Assess Compatibility: Analyze the existing APIs using Full Procurement Integration generic endpoints article to assess compatibility by comparing request/response specifications.
Things to know
ServiceTitan provides four main endpoints for supplier integration – Account, Branch (Default Branch), Pricing, and Purchase Order. To learn more about the endpoint configuration, see Full Procurement Integration generic endpoints.
Analyze the existing APIs using Full Procurement Integration generic endpoints article to assess compatibility by comparing request/response specifications. For APIs that are not compatible, you have two options:
Use the Middleware liquid templates to modify an existing API to accept/provide the data and bring it into compatibility with ServiceTitan.
Create a new API endpoint specifically for ServiceTitan using the generic endpoints templates.
For a seamless and efficient integration experience, download and use our CLI Tool. This tool is designed to streamline the integration process by automating key steps, reducing manual effort, and ensuring accuracy.
To explore more about ServiceTitan's supply chain integrations and supplier features, check out Available Supply Chain Integrations.
Visit our Full Procurement Integration knowledge base landing page to access all the relevant customer-facing articles about supply chain workflows in ServiceTitan.
Authentication process overview
Authentication for vendor integrations can be configured at two levels:
Supplier Level Configuration
Endpoint Level Configuration
By allowing supplier-level and endpoint-level configuration, this system offers a convenient yet flexible workflow. Supplier-level configurations streamline cases where most endpoints use the same authentication method or credentials, while endpoint-level settings ensure precision for unique or varying requirements.
This defines the type of authentication to be used (Basic, API Key, or OAuth2). ServiceTitan supports the following authentication methods, which can be applied globally or customized for individual endpoints:
Note: ServiceTitan allows multiple authentication methods to be used simultaneously for a single request.
GlobalBasic Authentication method
Basic Authentication is a straightforward method where credentials (username and password) are encoded in a base64 string.
Key Points
baseUrl: Specifies the base URL for the vendor's API endpoint.
kind: Indicates the authentication type as GlobalBasic, referring to Basic Authentication.
valueMappings:
OutputType: The value "Header" for Basic Authentication API requests.
Note: The other supported value is QueryString. However, it generally is not used for Basic Authentication because it can lead to credential leaks.
OutputKey: Maps to the header in the API request. You can change the name of the header (here it's Authorization) but this would rarely be done for Basic Authentication.
AuthenticationKey: Refers to the stored authorization value (e.g., username: password, encoded).
Prefix: Adds the "Basic" prefix to the Authorization header value.
Credentials
Secrets
User: A non-secret identifier (e.g., user or application ID).
Password: A secret token used for identity verification.
Outputs:
AuthorizationValue: Base64-encoded combination of user and password.
For more information, see Credentials management.
API Key Authentication method
ApiKey authentication involves providing a unique API key in the request header or URL parameter.
Key Points
baseUrl: Specifies the base URL for the vendor's API endpoint.
kind: Specifies the authentication method as ApiKey.
valueMappings:
OutputType: Placeholder for the header type or format.
OutputKey: Specifies the name of the header where the API Key should be included in API requests. While it is often "X-API-KEY," the exact header name depends on your system requirements, as this is not standardized.
AuthenticationKey: Refers to the unique API key used for authentication.
Credentials
Secrets
ApiKey: A single key used for authentication.
Outputs:
ApiKey: The retrieved API key.
For more information, see Credentials management.
OAuth2 Authentication method
OAuth2 offers a secure method of authorization by allowing systems to exchange credentials for an access token, which is then used to validate API calls. This method uses the Client Credentials flow to authenticate to the API as the ServiceTitan system. A Basic Authentication (Client ID and Client Secret) credential is used to obtain the token.
Key Points
baseUrl: Specifies the base URL for the vendor's API endpoint.
kind: Specifies the OAuth2 method, in this case, OAuthClientCredentialsBasicBearer.
valueMappings:
OutputType: Placeholder for the output type in the header.
OutputKey: Maps to the Authorization header in API requests.
InputKey: Denotes the key for the token provided by the OAuth2 server.
AuthenticationKey: Refers to the token used for authentication.
Prefix: Adds the "Bearer" prefix to the Authorization header value.
Credentials
Secrets
TokenEndpoint: URL to retrieve an access token.
ClientId: Identifier for basic authentication with the token endpoint.
ClientSecret: Secret token for basic authentication.
CredentialStyle: Determines how credentials are passed (header or body).
Scope: Scope to be passed to the token endpoint.
Outputs:
Token: Generated through client credentials flow.
For more information, see Credentials management.
Credentials management
Credentials management is where the credentials, such as usernames, passwords, API keys, or OAuth2 tokens, are configured. Supplier-level credentials act as a default for all endpoints, but you can define specific credentials at the endpoint level to override the supplier-level settings.
The workflow begins with setting up the Supplier or Endpoint configuration and proceeds to Credentials management, ensuring the supplier or endpoint exists before assigning credentials. Credentials are write-only. Once assigned, they cannot be retrieved through any API call.
Caution: Make sure to keep a record of any credentials assigned to ServiceTitan secured in your own credential management system.
GlobalBasic
Observables.authenticationKind: Specifies the use of GlobalBasic authentication.
applicableHosts: Lists the host(s) (endpoints) where these credentials apply. While the full vendorBaseUrl from the supplier configuration may be used as a convenience (e.g., in a Postman collection), only the host portion of the URL is used to determine the applicability of the credential.
Secrets:
User: Stores the username required for authentication.
Password: Stores the password, used in conjunction with the username.
API Key
Observables.authenticationKind: Indicates the use of ApiKey authentication.
applicableHosts: Ensures the API key is used only with the specified endpoint(s) defined in vendorBaseUrl.
Secrets.ApiKey: Holds the API key securely, used directly in requests to the endpoint.
OAuth2
Observables.authenticationKind: Defines the use of OAuth2 (OAuthClientCredentialsBasicBearer).
applicableHosts: Ensures the credentials apply to the relevant endpoint(s) (vendorBaseUrl).
Secrets:
TokenEndpoint: The URL where the access token is retrieved.
ClientId: Unique identifier for the client application.
ClientSecret: Secret associated with the client, used for token exchange.
