Introduction
A Private App in upgraded Planhat, ws.planhat.com (called a Service Account in original Planhat, app.planhat.com), is a special kind of account that's used by an application, not a person. You 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.
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 step)
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
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
Click the image to view it enlarged
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:
Click the image to view it enlarged
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
Once API Access Tokens are created, they will last forever, unless deleted
Any actions carried out via an API Token will show in Planhat as being done by the associated Private App