Skip to main content

How to set up Private Apps (Service Accounts) and API Access Tokens in Planhat

Christian Dreyer avatar
Written by Christian Dreyer
Updated over a month ago

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

  1. 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.

  2. In the "New App" ("Apps Library") modal, click on "+ Private app" in the top-left corner

  3. 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!

  4. 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

  5. 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

  • 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

Did this answer your question?