Skip to main content
All CollectionsTechnical cornerAPI
How to set up Service Accounts and API Access Tokens in Planhat
How to set up Service Accounts and API Access Tokens in Planhat

Everything you need to know about Service Accounts in Planhat

Christian Dreyer avatar
Written by Christian Dreyer
Updated over 3 months ago

Introduction

A Service Account is a special kind of account that's used by an application, not a person. You use Service Accounts 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 Service Account, which sets the scope of its API Access Token - exactly what actions it can be used to carry out.

⭐ Service Accounts provide many benefits:

  • Create and manage your own personal API Access Tokens

  • Have full control over what data the Service Account can access (by setting unique permissions)

  • View the API request history on the "Log" tab

  • Disable, enable and remove your Service Account at any point

📌 Important to note

The API Access Tokens you generate via Service Accounts 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 Service Accounts. See here for where to find your Tenant Token.

How to set up a Service Account and API Access Token

For a quick demonstration of setting up a Service Account, check out the GIF below - you can click it to open it enlarged. If you'd like to read detailed instructions in words, we list these below the GIF.

  1. Put your mouse over your avatar (initial or photo) in the bottom right of your Planhat tenant, and click on "Service Accounts"

    • 📌 Important to note: If you can't see "Service Accounts" as an option, that means your User doesn't currently have access to this feature. Speak to a colleague who's a Planhat admin if you think you should have access, and they can change your Role settings

  2. Click the blue "Add New" button
    ​

  3. A modal will appear:
    ​

    • Name - give your Service Account a suitable name

    • Copy Permissions From

      • Here you define which permissions the Service Account 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 Service Account

        • 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!

      • If you would like to know more about our permissions then check out this article 👍
        ​

  4. Your Service Account has now been created! It will open up a modal similar to this:

    • INFO - in this tab, you can add a description to explain what the Service Account is used for, and generate API Access Tokens (as described in the next step)

    • PERMISSIONS - here you can set/edit the Service Account permissions (what the API Access Token can be used for)

    • LOGS - view your API request history

  5. Click the blue "Generate New Token" button at the bottom of the "INFO" tab 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

  6. You can now close the modal

Managing existing Service Accounts and API Access Tokens

Once you've created Service Accounts, the main "Service Accounts" page will look something like this:

You can use the toggle switch to quickly disable/enable a Service Account, and use the bin (trash can) icon if you'd like to delete that Service Account.

To open a Service Account - e.g. if you would like to view or change its permissions - simply click on the Service Account in the list to open up its modal. You can delete a particular API Token here without having to delete the whole Service Account. (Note that, as mentioned above, you won't be able to view an API Access Token itself again.)

Further details

  • Service Accounts do not have passwords, and cannot log in via browsers or cookies

  • Service Accounts are not team members (Planhat Users). They will not appear in User lists

  • You need to have the "Serviceaccount" permission enabled to view "Service Accounts" as an option when you mouse over your avatar

  • 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 Service Account

Did this answer your question?