Summary
The OAuth Client feature allows external applications to connect to Planhat and interact with Planhat data, on behalf of a user, after they give permission, without sharing passwords
You could use a Planhat OAuth Client to connect to an external AI provider's LLM via Planhat's MCP Server
In another use case example, if you are a developer at an integration partner, you could could build an OAuth application so customers can authorize access and let that tool read and process their Planhat data
Permissions can be set within the OAuth Client, or you can have "dynamic permissions" that are configured per user authorization. User Roles and OAuth scopes also limit permissions
Users can disconnect any applications they connected to, if desired
Who is this article for?
Technical teams and developers, including integration partners building third-party applications to connect into Planhat
General Planhat business users, who may be connecting to or disconnecting from OAuth applications
This feature is currently in beta.
Series
This is the first article of two about Planhat OAuth Clients.
Article two is our technical deep-dive article, here.
Article contents
Introduction
In Planhat, you can create OAuth Clients within the App Center. They allow external applications (other software tools, outside of Planhat) to safely and securely access specific Planhat data, after users give permission.
Access tokens generated via Planhat OAuth Clients allow external applications/integrations to communicate with Planhat via the Planhat API. Here we are talking about standard "Create" "Update" "Delete" etc. operations, acting on Planhat data models, rather than using the API to sync time-series data (Planhat custom metrics and user activities).
In a key use case, Planhat OAuth Clients can be used in combination with Planhat's MCP Server to connect to AI tools - see links in the "Tip" box below.
🚀 Tip
If you are looking for instructions specifically for connecting Planhat's MCP Server to external AI providers' LLMs via OAuth, please refer to our separate MCP documentation here.
Specifically, you can see instructions for:
In another main use case, which we focus on in this article, you may be a developer (integration partner) building your own application/integration to connect into Planhat, viewing and interacting with Planhat data on behalf of a user.
Info for business users
As many readers of this article will be familiar with the general concepts of OAuth Clients, we are not going to cover background details within this introduction. Instead, if you would like to read about the main principles and also how this fits into Planhat's suite of related features, check out our intro for general business users (non-developers) here (positioned as an appendix towards the end of this article).
The other part of the article that's most relevant to general business users is how to disconnect an OAuth application that you previously authorized - you can read how to do that here.
How to set up a Planhat OAuth Client
Preliminary step by Planhat staff: Planhat Labs
At time of writing, to access this feature (in beta), it first needs to be enabled by a Planhat staff member ("Super Admin") via Planhat Labs, itself accessed in the "Help" menu.
Creating a new OAuth Client in Planhat
🚀 Tip
Remember, if you are looking for instructions specifically on connecting Planhat's MCP Server to external AI tools via OAuth, please refer to our separate MCP documentation here.
In Planhat, go to the App Center
To do this, click on your tenant name or icon/initial in the top left to open up the "System Admin" menu, and click "App Center"
Click "+ New app" in the top right
Click the image to view it enlarged
Click "+ OAuth Client" in the top left of the Apps Library
Click the image to view it enlarged
Enter a name for your OAuth Client, and click "Create"
Complete the "General" tab of this form that opens up
Please note that for security reasons, the Client Secret is only shown once, so you should copy it now and store it securely
If you went to look at it in Planhat later, the only option would be to generate a new Client Secret, which would mean that the previous Secret would stop working
At the top of the form, you choose whether the "Client Type" is "Confidential" or "Public"
Confidential Clients run on secure servers, where their credentials can be kept secure. They can use Client Secret, PKCE or both
Public Clients run in environments where credentials cannot be securely stored, such as mobile and web apps. They need to use PKCE
"PKCE" is again a general OAuth concept, not something Planhat-specific
Next, click on the "Permissions" tab to configure the permissions
Here you can define the maximum permissions that can be requested/authorized via this OAuth Client
You have granular control over Create/View/Update/Remove/Export for each data model, and you can click on each data model to open up its nested properties (fields)
You may notice that this is very similar to the data model permissions you'll be familiar with from Roles, and also the permissions you set in Private Apps (Service Accounts)
Permissions can then be further limited by OAuth scopes: the external application using the OAuth Client can request less access than that specified within the OAuth Client
The Roles of the users then authorizing via the OAuth Client will also limit access: a user cannot authorize greater access than they have in their Role. This can potentially lead to an "OAuth permission check failed: missing permissions" error if e.g. (1) a Planhat admin creates an OAuth Client with lots of permissions; (2) an external application requests access to the "default" scope, which means all these permissions; (3) a user with a different Role with less access (fewer permissions enabled) then tries to authorize the external application via that OAuth Client. One workaround to this would be to create/use a different OAuth Client per Role. An alternative is described in the next point ...
Instead of specifying the maximum permissions in the OAuth Client, there is a setting that can be enabled, called "Enable dynamic permissions". This is a toggle switch at the top of the "Permissions" tab, which can only be enabled by a Planhat "Super Admin" (i.e. Planhat staff member) - so please speak to a Planhat representative if you would like this to be turned on. If enabled, then no permissions are specified in the OAuth Client, and instead, each user sets permissions at the point they authorize the external application. We discuss this further here
Another option to be aware of is the "Allow additional custom fields" toggle switch at the top of the "Permissions" tab. Like "Enable dynamic permissions", this can only be enabled by a Planhat "Super Admin" (Planhat staff member). However, unlike "Enable dynamic permissions", this option is actually used in combination with setting data model permissions within the "Permissions" tab. It enables users to choose to give access to additional custom fields that were not specified by the OAuth Client creator, solving for the scenario where certain fields exist in the connecting user's tenant but not the OAuth Client creator's tenant. We talk more about this here
When you have finished configuring your OAuth Client, press "Save" in the top right
You can now start using your OAuth Client with your external application/integration, via the Client ID and Client Secret
You will see saved OAuth Clients in a specific tab within the App Center (as well as the "All apps" tab).
Click the image to see it enlarged
Private and Published OAuth Clients
We mentioned above that the Client Types of "Confidential" and "Public" are standard OAuth terms, rather than something Planhat-specific.
"Private" and "Published" OAuth Clients might sound similar but actually describe different concepts, and these are Planhat-specific terms.
"Private Client" - an OAuth Client created by and for you and your co-workers
A Private Client can only be used (authorized) by users within the Planhat tenant where it's been created
This is the default for Planhat OAuth Clients
"Published Client" - an OAuth Client created for your customers
"Published" means the OAuth Client can be used (authorized) by users in different Planhat tenants
Only Planhat staff can publish OAuth Clients, after they have been approved
🚀 Tip
To learn more about Private and Published OAuth Clients, check out our separate technical deep-dive article here.
Authorization process
🚀 Tip
Remember, if you are looking for instructions specifically on connecting Planhat's MCP Server to external AI tools via OAuth, please refer to our separate MCP documentation here.
The description below will be for a more general use case, particularly regarding building your own external application/integration.
🚀 Tip
In this article we are not going to cover the development of the external application/integration (third-party software, outside of Planhat), which is the responsibility of the integration provider.
However, we can provide the following URLs that you will need when building this external application/integration. You will see that these are used in the authorization process detailed below.
Where to redirect to, to start the authorization flow:
ws.planhat.com/oauth/authorizeWith all of the related parameters:
client_id,scope,redirect_urietc.
Where to trade your authorization code for a access/refresh token pair:
api.planhat.com/oauth/token
Once the OAuth Client and the external application/integration are set up, the general process would be as follows - using viewing the "Company" Planhat data model as an example:
Participants:
a user in a Planhat tenant who has access to Companies
a third-party integration provider, with an external application outside of Planhat, which wants to read Companies in Planhat
Planhat itself
The user is a customer of both the external integration provider and Planhat
Example process:
The user is using the integration provider's external application, and wants to grant it access to Planhat to read their Companies
The user clicks on "Authorize" or "Connect" (or similar) within the external application
That redirects them to Planhat (using the first URL in the "Tip" box above:
ws.planhat.com/oauth/authorize), which prompts the user to log in (if they aren't logged in), and then the user sees a consent modal, asking them to confirm whether they would like to grant the external application access to read their Companies. (In this example scenario, these permissions have been set in the OAuth Client.) The user authorizes this requested accessPlanhat redirects the user back to the external app, and provides it an authorization code
The external app converts that authorization code to an access/refresh token pair (via the second URL in the "Tip" box above:
api.planhat.com/oauth/token), and can now read the relevant Planhat Companies on behalf of the user
Let's go through a couple of illustrated practical examples.
Example 1: permissions specified in OAuth Client
We have specified full permissions for the Company model within this example OAuth Client, as you can see in the screenshot below:
For a Planhat user to enable an external application/integration to give access to Companies in their tenant via this OAuth Client, they would click on "Connect" or "Authorize" (or similar) within the external tool. They will see a modal similar to this:
The user can review what access is being requested in this consent screen - there's some key information displayed as default, and then clicking "Show more" gives further details, and mousing over the "i" gives further details still.
The user can click "Cancel" if they don't want to proceed with the connection, or "Authorize" to authorize the external application/integration.
If authorized, the application/integration receives an authorization code (alongside any PKCE parameters), and converts that authorization code to a refresh/access token pair.
The access token is short-lived - it will be available for about one hour
The refresh token is a longer-lived token - it will work for one year. However, each refresh token only works once; you cannot reuse it. (An attempted reuse of the refresh token would cause the entire connection to get disconnected)
After the authorization is completed, with that access token, the external application/integration can make requests towards the Planhat API on behalf of the user.
User Role permissions
It's important to note that the permissions specified in the OAuth Client represent the maximum possible access when a user connects to the relevant external application/integration - but the access that each specific user has in Planhat applies an additional limit on top of that.
In Planhat, the access of each user is determined by Roles, which you configure in the "Settings" Global Tool. Data model permissions define access to Planhat data models, and portfolio permissions determine which Companies a user has access to.
For example, if a particular Planhat user's Role portfolio permissions means they can only access the 5 specific Companies where they are the Owner, and then they authorize an external application/integration via an OAuth Client that has been configured to have full Company permissions, then the external application/integration will only have access to those 5 Companies via that user authorization, rather than all the Companies in the user's Planhat tenant.
🚀 Tip
To read about the different consequences of increasing or decreasing permissions either in the user's Role or in the OAuth Client after the authorization has already occurred and access granted, check out our technical deep-dive article here.
📌 Important to note
A Planhat user cannot authorize greater access than they have in their Role.
This can potentially lead to an "OAuth permission check failed: missing permissions" error if, for example:
(1) a Planhat admin creates an OAuth Client with lots of permissions
(2) an external application requests access to the "default" scope, which means all these permissions
(3) a user with a different Role with less access (fewer permissions enabled) then tries to authorize the external application via that OAuth Client
One workaround to this would be to create/use a different OAuth Client per Role.
An alternative is to not set permissions within the OAuth Client, and instead enable the toggle switch to use dynamic permissions instead. We describe the dynamic permissions authorization method next in this article.
Example 2: dynamic permissions
Let's take a look at the process where the "Enable dynamic permissions" toggle switch has been turned on (by a "Super Admin" - Planhat staff member) for the OAuth Client.
Remember, if dynamic permissions have been enabled, then you don't specify any permissions within the OAuth Client. Instead, the permissions are dynamically configured by each user connecting via it.
In this case, when a Planhat user goes to enable an external application/integration using this OAuth Client, the authorization modal/process looks slightly different. Rather than just being told the permissions being requested, with the ability to accept ("Authorize") or deny ("Cancel"), now they will actually select their choice of permissions here, as shown below. (Note that this is limited by the user's Role permissions, so they won't be able to give the external application access to data that they don't themselves have access to in Planhat.)
Each user who connects will need to select the specific access that they want to grant. This means that users with different access levels in Planhat (e.g. a user with a CSM Role in Planhat will typically have fewer permissions enabled compared to a user with an Administrator Role) can all still authorize using the same OAuth Client, even if the external application requests the access of the "default" scope (meaning everything).
A typical use case for this setup would be connecting to Claude via Planhat's MCP Server.
Example 3: allow additional custom fields
Finally, let's see what it can look like if the "Allow additional custom fields" toggle switch is enabled.
In this example, let's say that the OAuth Client has permissions enabled for the Company model - specifically View and Update (i.e. Edit) - and has this toggle switch turned on.
For the connecting user, if they have access to additional custom fields on the Company model, their authorization model will look similar to this:
Clicking on "Custom fields - Grant additional field access" (annotated in green in the screenshot above) will open up a modal like this:
The user can use the dropdown menus if they would like to give access to any of the named fields. The dropdown menus allow selection of the desired level of access (e.g. "View" v. "View & Edit" in the example screenshot below).
Once the user has made their choice, they can click the "Done" button. The text will update to show that additional fields are configured (as shown in the screenshot below). From here, the user can still click into this if they want to change the configuration, or otherwise, once they are ready, they can click "Authorize" to authorize as usual.
Audit Events
Within each Planhat OAuth Client, you'll find a tab called "Audit Events" (which you may also hear referred to as "Audit Logs").
This security feature automatically tracks events related to the OAuth Client, enabling you to monitor activity and understand what has happened, without needing to ask Planhat staff for logs. A wide range of actions are included:
You can apply different filters (dates/actions/users) if you are looking for something specifically.
Note that Audit Events (Audit Logs) are specific to your own tenant, so you can only see actions by users in your own tenant (even if it's a Published Client in use by multiple tenants).
For general business users
What are OAuth Clients?
Info for business users
The following information is provided for Planhat users who are non-developers and who do not have prior experience with OAuth Clients.
It provides some background context on the advantages of OAuth in general, and how OAuth Clients compare to other Planhat features that general Planhat users may be familiar with.
If instead you are a developer or in another technical role and are already very familiar with OAuth, you can skip this part of the article.
OAuth background information - general concept and advantages
Note that this is not specific to Planhat.
OAuth 2.0 is a method of online authorization, enabling an application to access data hosted by another application on behalf of a user. The level of access (permissions) are specified and limited, and the user authorizes the access without sharing their credentials.
OAuth 2.0 can be thought of as an upgraded option compared to the earlier method of API keys (static API tokens), with better security and flexibility. With OAuth Clients:
Users can approve applications/integrations securely
Access is tied to a specific user and permissions
Applications/integrations can be disconnected instantly by users if they no longer want to give access
Partners can build reusable applications/integrations for multiple customers
Refresh tokens are used as well as access tokens
Planhat OAuth Clients - interaction with other Planhat features
Access tokens generated via Planhat OAuth Clients allow external applications/integrations to communicate with Planhat via the Planhat API. Here we are talking about standard "Create" "Update" "Delete" etc. operations, acting on Planhat data models, rather than using the API to sync time-series data.
In one common use case, Planhat OAuth Clients can be used in combination with Planhat's MCP Server to connect to AI tools - LLMs:
Planhat OAuth Clients - comparison with other Planhat features
You may be wondering how OAuth Clients compare to other Planhat features you may already be familiar with, such as Private Apps (Service Accounts) for interacting with Planhat data from an external application, or the OAuth "Connections" you can also create in the App Center. When do you use one and not the other? We explain the similarities and differences below.
OAuth Clients fulfill a role that's similar to Planhat "Private Apps", formerly called "Service Accounts"
Like OAuth Clients, you also create these in the App Center to interact with Planhat data from an external application via the Planhat API, but these work via API keys
With Private Apps, you create a specific "Service Account"-type user with its own set of permissions, but with OAuth Clients, each connected (human) user's own Planhat Role permissions limit the access granted (in addition to the maximum possible permissions being specified in the OAuth Client)
Some external applications will only connect into Planhat via an OAuth Client due to their security requirements; Private Apps (Service Accounts) are not sufficient
Also within the App Center, you can create "Connections", with a choice of authentication type including OAuth 2.0, but this is involving the opposite part of OAuth compared to OAuth Clients:
The Connection feature allows Planhat to become the consumer: the third-party app accessing another OAuth 2.0 provider, and access data/endpoints from the connected provider ...
... whereas the OAuth Client feature makes Planhat the provider, so other apps can connect to it and read data from Planhat, on behalf of a user
Although you can use "Connections" within Planhat Automations (including "Light Integrations"), OAuth Clients are not relevant to that setup, because OAuth Clients are for use with systems operating outside of Planhat (external apps connecting into Planhat), rather than Automations which operate inside of Planhat (and can connect out of Planhat e.g. to fetch data to bring it in)
How a user can disconnect an external application
Info for business users
The following section is relevant to general business users, rather than being aimed at those configuring OAuth Clients or external applications.
If you (as a Planhat user) have authorized access and connected to an external application/integration, but then later on you want to revoke that access, you can disconnect that external application from within Planhat, so it can no longer access your Planhat data on your behalf.
To disconnect an OAuth Client, you need to go to the "Applications" tab in your User Profile.
🚀 Tip
If you cannot see the "Applications" tab in your User Profile, the tab needs to be added to the Full-Page Profile Template. For details of how to do this, please refer to our separate technical deep-dive article here.
It's important to note that the connected applications/integrations shown here are based on you as a user - which external applications you have given access to. "Connected since" (shown in the screenshot above) refers to when you specifically connected your personal Planhat user account to that external application to give it access into your tenant.
This tab does not show any OAuth Clients you created (as described in the rest of this article) or connections to them.
To disconnect an application, click on the "Disconnect" button:
Once you click "Disconnect", this modal (screenshot below) will show, where you can confirm whether or not you want to proceed with disconnecting the application / OAuth Client.
As soon as you disconnect an application, each related token will stop working - this means that it cannot access your Planhat data going forward.