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 where 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
Series
Planhat OAuth Clients - overview ⬅️ You are 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 also refer to our separate MCP documentation:
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
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 also refer to our separate MCP documentation:
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"
This will open up a form to complete, as shown in the screenshot below:
Note that the "External App" tab is only visible for Planhat "Super Admins" (Planhat staff)
If your OAuth Client is for you (and your organization) to connect to Claude or ChatGPT via the Planhat MCP server, click on the "MCP for Claude" or "MCP for ChatGPT" buttons as appropriate, and this will automatically fill in the relevant details in this form
Note that for ChatGPT, the "Redirect URL" is unique to your own ChatGPT setup, so you will still need to enter the relevant URL here (see instructions in our separate article here)
Otherwise, you can leave "Custom" selected, which means nothing is prefilled, and you should manually complete the form
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
In all cases, please note that the Client Secret is only shown once (for security reasons), 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
Next, click on the "Permissions" tab to configure the OAuth Client permissions
There are two main options here, based on whether the "Enable Admin-level Permission Control" toggle switch is enabled or disabled
If it's enabled (as shown in the screenshot above), then here you specify the maximum data model permissions for the OAuth Client
Each individual connecting user will also be limited by the permissions in their Planhat Role. If the OAuth scope used is "inclusive" (which is applied as standard when connecting to ChatGPT/Claude via Planhat's MCP server), then each user will be able to grant access to the intersection (overlap) between the permissions enabled in the OAuth Client and the permissions enabled in their Role. For example, if the OAuth Client has Company and Issue selected in its permissions, and then a user with permissions for just Company and End User tries to connect, then the result will be that the Company permissions are granted in the authorization
However, note that if the "default" OAuth scope is applied (e.g. in a custom application/integration you build outside of Planhat), then that will request access to all permissions defined in the OAuth Client, and so a user with fewer permissions enabled in their Role will not be able to authorize that access level and would get an error
If this toggle switch is disabled, then none of the data model permissions are shown in the OAuth Client, and instead, each individual user will be prompted to select which data model permissions to enable in their authorization
Each user will only be able to enable permissions that are enabled in their Planhat Role - but this time the OAuth Client is not providing an additional limit, and each user has more manual work but can enable a more personal level of access
We go through examples of what the authorization looks like with these two options later in this article
Further details:
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 these permissions are very similar to the data model permissions in Roles, and also the permissions you set in Private Apps (Service Accounts)
As mentioned above, in addition to permissions limits set in the OAuth Client and user Roles, 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
If you are building an external app (for your customers in multiple Planhat tenants, rather than just for you and your co-workers in your own tenant), speak with your Planhat representatives to complete the "External App" tab, which we describe below
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).
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/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 - also known as an "external app"
"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.
"External App" tab
As we've previously mentioned, there is an "External App" tab in the OAuth Client setup form, but it is only visible to Planhat "Super Admins" (i.e. Planhat staff members) - so speak with the Planhat team if you need it filling out.
This tab is not relevant if, for example, you're setting up an OAuth Client for you and/or your colleagues to connect to Claude or ChatGPT via Planhat's MCP server. It is applicable to you if you want to publish your OAuth Client so that people in other Planhat tenants (your customers) can connect using it too - let's say you are developing your own application/integration.
As well as some "Legal & Compliance" details to add (e.g. your Help Center URL and your contact details for your customers), here there is a toggle switch "Enable custom fields across tenants". This permission option is used in combination with setting data model permissions within the "Permissions" tab of the OAuth Client. It enables users (your customers) to, when they connect/authorize, choose to give access to additional custom fields that were not specified by the OAuth Client creator (you), solving for the scenario where certain fields exist in a connecting user's (a customer's) tenant but not the OAuth Client creator's (your) tenant. We talk more about this 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:
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 an 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 ("View") 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 ("View") 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 access to Companies in their tenant via this OAuth Client, they would click on "Connect" or "Authorize" (or similar) within the external tool. They would then 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, 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 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.
If the OAuth scope is set to "inclusive" (which is automatically applied when connecting with MCP servers, such as Planhat's MCP server to connect to Claude or ChatGPT):
The permissions set in the OAuth Client are the maximum, but it won't lead to an error/failure if a user with fewer permissions tries to connect - they will simply authorize the appropriate limited access (the intersection of the OAuth Client permissions and the user's Role permissions)
For example, if the OAuth Client has Company and Issue selected in its permissions, and then a user with permissions for just Company and End User tries to connect, then the result will be that the Company permissions are granted in the authorization
However, if the OAuth scope is set to "default", this can potentially lead to an "OAuth permission check failed: missing permissions" error if, for example:
A Planhat admin creates an OAuth Client with lots of permissions
An external application requests access to the "default" scope, which means all of these permissions
A user with a different Role with less access (fewer permissions enabled) then tries to authorize the external application via that OAuth Client
In addition to using the "inclusive" scope rather than "default", another workaround to this error would be to disable the "Enable Admin-level Permission Control" toggle switch in the OAuth Client to enable dynamic permissions instead, which we discuss in the next example.
Example 2: dynamic permissions
Let's take a look at the process where the "Enable Admin-level Permission Control" toggle switch is turned off for the OAuth Client.
Remember, in this case, you don't specify any permissions within the OAuth Client. Instead, the permissions are dynamically configured by each user connecting to 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) rather than "inclusive" (the intersection of OAuth Client permissions and Role permissions).
Example 3: allow additional custom fields
Finally, let's see what it can look like if the "Enable custom fields across tenants" toggle switch is enabled (by a Planhat "Super Admin" - staff member).
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 modal 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.