Skip to main content

Authorization

Follow this guide to create a new Planhat credential that will allow Nexla to authenticate to and exchange data with your Planhat account.
planhat_api_auth.png

Planhat

Prerequisites​

The Planhat connector authenticates using a static Bearer API Access Token issued by a Planhat Service Account (also called a Private App in newer Planhat workspaces). Before creating a Planhat credential in Nexla, you must generate a token in Planhat.

Generate a Planhat API Access Token​

Planhat API Access Tokens are tied to Service Accounts, which are purpose-built accounts designed for integrations rather than individual users. Tokens are static (non-expiring) and are displayed only once at creation time, so you must copy and store the token securely before leaving the page.

  1. Sign in to your Planhat workspace.

  2. Navigate to Settings in the left-hand navigation menu, then select Service Accounts.

    In newer Planhat workspaces (ws.planhat.com), Service Accounts have been renamed Private Apps and are found in the App Center global tool rather than Settings. The steps below apply to both experiences—the UI labels may differ slightly.

  3. Click Create Service Account (or + Private App in newer workspaces) to begin creating a new service account for the Nexla integration.

  4. Enter a descriptive name for the service account—for example, Nexla Integration—so it is easy to identify later.

  5. Configure the permissions for the service account. Planhat allows you to restrict each service account to specific data models and access levels:

    • For a read-only integration (Nexla as data source only), grant the service account read permissions on the Planhat data models you intend to sync. Relevant models for the Nexla connector include Companies, End Users, Licenses, NPS, Conversations, Tickets, Tasks, Issues, Invoices, Opportunities, and Churn.

    • For a read-write integration (Nexla as both data source and destination), also grant write permissions on any data models Nexla will create or update records in.

    Granting only the minimum permissions required for your use case is a security best practice and reduces the blast radius if the token is ever compromised. Additional details about Planhat data model permissions are available in the Planhat Help Center.

  6. Click Save (or Create) to save the service account.

  7. On the service account detail page, click Generate New Token (or Generate API Access Token) to create an API Access Token for this service account.

  8. Copy the generated token immediately and store it in a secure location such as a password manager or secrets vault. Planhat displays the token only once—it cannot be retrieved again after you navigate away from the page.

    Important

    If you navigate away without copying the token, you will need to generate a new token. The old token will remain active until explicitly disabled or the Private App is paused or deleted.

For complete information about setting up Service Accounts and API Access Tokens, see the Planhat Help Center article on Private Apps and API Access Tokens.

Create a Planhat Credential​

  • To create a new Planhat credential, after selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

Credential Name & Description​

  1. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

    Resource descriptions are recommended but are not required. They should be used to provide information about the resource purpose, data freshness, etc. that can help the owner and other users efficiently understand and utilize the resource.

API Access Token​

  1. Enter the Planhat API Access Token you generated in the Prerequisites section above into the API Access Token field. This token authenticates Nexla with the Planhat API using Bearer token authentication and must correspond to a Service Account with the appropriate permissions for your intended use (reading data, writing data, or both).

    The API Access Token is a sensitive credential. Nexla stores it securely and encrypts it at rest. Do not share this token or include it in log files or source control.

Save the Credential​

  1. Once all of the relevant steps in the above sections have been completed, click the Save button at the bottom of the overlay to save the configured credential.

  2. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation and can be selected for use with a new data source or destination.