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 are set within the OAuth Client, but are also dependent on the user connecting to the external application
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, you would find that the only option was 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 define the maximum permissions that this OAuth Client can request
Permissions can then be further limited by OAuth scopes, and by the Roles of the users authorizing via the 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)
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. The user approvesPlanhat 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 an illustrated practical example.
We have given 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 check 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.
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.