Dev Portal, App key and Client ID & Secret Key

How do I login to the My apps tab ? 

In order to login to the My Apps tab of the dev portal, your ServiceTitan admin needs to establish you as a user in your organization's integration environment or the production environment instances. Once you are established with user credentials, you can use those credentials to login to the My Apps tab. 

How is the app key generated ?

After you login to the My Apps tab of the dev portal, you will create an app, add tenant IDs, and choose API scopes. Once these steps are completed and saved, your app key is generated.

Who and how should the Client ID & Secret Key be generated ?

User with admin permissions (that is who has the 'Manage API Application Access' permission) will review applications requesting access to the resources and will generate a Client ID and Secret Key for that app and then share it with the developer of that application.

Application manager can also self-generate the Client ID and Client Secret pair by configuring the application following the steps outlined in the API Documentation here.

I created my App previously. Can I want to add new API endpoints to my previously created App ?

Yes. Please log into the developer portal. Choose the App you want to add/remove API scopes by clicking the Edit button. Add/Remove the API scopes. Click Save. Note: Each time the API scopes are edited a new version number of the App is generated. New API scopes will come into effect only after the Tenant admin Accepts the new version of the App.  There is no need to update the App key or Client ID & Secret key. 

Do I need to recreate the App if I am adding new API endpoints to my App ?

No. Please log into the developer portal. Choose the App you want to add/remove API scopes by clicking the Edit button. Add/Remove the API scopes. Click Save. Note: Each time the API scopes are edited a new version number of the App is generated. New API scopes will come into effect only after the Tenant admin Accepts the new version of the App.  There is no need to update the App key or Client ID & Secret key. 

I am a ServiceTitan customer and have multiple tenants. Can a single pair of Client ID & Secret work for all tenants ?

Yes, if your organization uses Enterprise Hub. In Enterprise Hub, via API Credentials Management Portal, customers can create networks of tenants that will share a single Client ID & Client Secret pair.

As of today, Enterprise hub is only offered to ServiceTitan customers and not to the 3rd party partners and developers.

Multiple ServiceTitan customers will use the app I am creating. Will the same app key, Client ID and Secret Key work for all of them ?

Since the app key represents the application, you can use the same key for multiple customers/tenants. Since Client ID & Secret Key are unique to each ServiceTitan tenant, you need to obtain an application and tenant specific Client ID & Secret Key from the ServiceTitan admin of each customer/tenant. For example, if you have an application that will be used by 10 ServiceTitan customers/tenants, you need to obtain 10 Client IDs & Secrets Keys but can use the same app key. 

Why are Tenant IDs added while creating an app ?

As an application developer you need to add the Tenant IDs of the customers whom you want to let to use your app. By adding Tenant IDs, ServiceTitan admins at the customer organizations can discover your app and would be able to generate and enable the Client ID & Secret Key and share it with you. You can add any number of tenant IDs, and can add and remove tenant IDs at any time even after the app has been created. 

Does ServiceTitan follow OAuth 2.0 protocol ?

Yes, with the advent of V2 APIs ServiceTitan now uses the OAuth 2.0 machine to machine client credentials grant flow.

As an app developer, am I able to manage my tenant’s Client ID and Client Secret through the developer portal?

Yes. You have the option to self-generate a tenant’s Client ID and Client Secret by configuring your app for self-service under your app details page in your developer portal. Follow the instructions under Docs → Client ID & Secret section of the developer portal for more details.

I currently receive the Client ID and Client Secret directly from the tenant admin, am I able to update my app to the self-service client option?

Yes. You can update how you receive the Client ID and Client Secret by updating your existing app to allow for self-service. Follow the instructions under Docs → Client ID & Secret section of the developer portal for more details.

I do not see the ability to generate the Client Secret key and it says 'Not Connected Yet'. What should I do?

In order to generate the Client Secret for a tenant, a tenant admin first needs to connect to your app under Settings → API Application Access → Connect New App within their account. If they have not yet connected, you will see the “Not Connected Yet” message for the tenant under your app connections.