📌 Important to note
Private Apps (Service Accounts) are an older technology, with static tokens.
OAuth Clients were introduced more recently, and are preferable in many cases.
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 in those cases.
For more on OAuth Clients, please refer to our series of articles starting here.
Introduction
A Private App (previously called a Service Account) is a special kind of account that's used by an application, not a person. You can use Private Apps to generate and manage API Access Tokens. Applications can then use the API Access Tokens to make authorized API calls to Planhat.
You can define the permissions of each Private App, which sets the scope of its API Access Token - exactly what actions it can be used to carry out.
⭐ Private Apps provide many benefits:
Create and manage your own personal API Access Tokens
Have full control over what data the Private App can access (by setting unique permissions)
View the API request history on the "Logs" tab
Disable, enable or delete your Private App at any point
📌 Important to note
The API Access Tokens you generate via Private Apps are used with the main Planhat API endpoint, to create/update/delete model records, such as Companies or End Users.
If you want to send time-series usage data (User Activities and Custom Metrics) to Planhat via the API, you instead use the analytics endpoint, with your Tenant Token (Tenant UUID) rather than Private Apps. See here for where to find your Tenant Token.
📌 Important to note
Previously, once API Access Tokens were created via Service Accounts, they lasted forever, unless deleted. However, this is no longer the case.
When you create a new Token via a Service Account, you will set an expiry date (default 30 days; maximum 365 days).
Previously-created Tokens with no expiration date are now deprecated, and it's expected that they will be invalidated in a future release (although no date has been set at time of writing), so we recommend that you generate a new Token with an expiration date to replace each of these old ones.
How to set up a Private App and API Access Token
Go to the "App Center" Global Tool
Either: click on "Private apps" if you would like to view and manage existing Private Apps
Or: click "+ New app" if you would like to add a new Private App - the rest of these instructions will follow this pathway
Click the image to view it enlarged
(Note that access to Private Apps is controlled by the "ServiceAccount" data model permissions)
In the "New App" ("Apps Library") modal, click on "+ Private app" in the top-left corner
In the modal that appears:
Name - give your Private App a suitable name
Copy Permissions From
Here you define which permissions the Private App has (so what its associated API Access Token will be able to do). Note that you can change this later if required
You have the option to:
Start from scratch
Use the permissions of your choice of existing Private App
Use the permissions of your choice of existing Role
This is great because you don't need to start from scratch each time you want to define permissions!
Click "Create" in the bottom right (shown in the screenshot above) to create your Private App. This will open up a modal similar to this (shown below), where you can make changes - remember to press "Save" in the top right when you have finished editing
Click the image to view it enlarged
Info - in this tab, you can add a description to explain what the Private App is used for, and generate API Access Tokens (as described in the next steps)
Permissions - here you can set/edit the Private App permissions (what the API Access Token can be used for)
Logs - view your API request history
Choose how long you want your Token to be valid from, using the "Set Expiration" dropdown menu (shown in the screenshot above)
The maximum you can set this to is 365 days
Click the "Generate new token" button at the bottom of the "Info" tab (shown in the screenshot above) to generate your API Access Token
📌 Important to note: The API Token will only be displayed this once, so make sure you copy it and store it securely. If you lose it and need it again, you will need to generate a new API Token
Managing existing Private Apps and API Access Tokens
Once you've created Private Apps, the "Private apps" part of the App Center will look something like this:
You can use the toggle switch to quickly disable/enable a Private App, and use the bin (trash can) icon if you'd like to delete that Private App.
To open a Private App - e.g. if you would like to view or change its permissions - simply click on the Private App in the list to open up its modal. You can delete a particular API Token here without having to delete the whole Private App. (Note that, as mentioned above, you won't be able to view an API Access Token itself again.)
Further details
Private Apps do not have passwords, and cannot log in via browsers or cookies
Private Apps are not team members (Planhat "Users"). They will not appear in User lists
You need to have the "ServiceAccount" permission enabled to view "Private apps" as an option
"ServiceAccount" is a data model permission
Any actions carried out via an API Token will show in Planhat as being done by the associated Private App
When Tokens are about to expire (7 days or fewer to expiry, excluding Tokens where the original expiration is less than 7 days), the creator of the Service Account will receive an email notification. If they don't take action, then when the token expires, they'll also receive an email informing them of the expiry. If the Service Account doesn't have a "creator" (which could be the case for a legacy Service Account), the tenant Administrators will be notified instead of the creator
As we mentioned earlier in this article, previously-created Tokens with no expiration date are now deprecated, and it's expected that they will be invalidated in a future release (although no date has been set at time of writing), so we recommend that you generate a new Token with an expiration date to replace each of these old ones