How Do I Generate and Manage Piano ESP API Keys?

The Piano ESP API key authenticates server-side calls made to ESP endpoints — for example, subscribing or unsubscribing users, querying subscription status, updating merge fields, or pulling campaign statistics. This article describes how to generate, access, secure, and troubleshoot ESP API keys across environments.

Key facts before you start

• The ESP API key is product-specific. It is not the same as a Piano Analytics token, a Identity Management API token, or the application Private Key. Calls to ESP endpoints will fail if you use a key from another Piano product.

• Each ESP Site has its own API key. Production and sandbox sites have separate, non-interchangeable keys, and each region (US, EU, AP) has its own production site and key.

• Only users with the Admin role in ESP can view or generate API keys. If you do not have the role, ask a colleague who does, or contact Piano Support.

• Generating a new API key invalidates the previous key immediately. Update every integration that uses the old key before — or as soon as — you rotate it.

Generating or retrieving an API key

1. Confirm your role. You need the Admin role in the ESP system to view or create API keys.

2. Open the correct ESP dashboard. Log in to the dashboard for the environment you need:

   • Production (US): https://esp.piano.io

   • Sandbox: https://sandbox-esp.piano.io

   • Regional production dashboards exist for the EU and Asia-Pacific regions.

3. Select the correct Site. The Site ID is shown in the top-left of the ESP interface. Make sure it matches the application you want to manage.

4. Navigate to Setup → Integrations. In the Integrations screen, look at the top right:

   • If an API key already exists, click the copy icon (or hover the "i" information icon) to copy it.

   • If no key exists, contact Piano Support and provide:

     • The ESP Site ID (also shown as the Application ID)

     • The environment (sandbox or production, and the region)

5. Repeat per site and per environment. If you operate in both sandbox and production, or across multiple regional sites, you will need a distinct key for each.

Using the API key

When calling an ESP endpoint, pass the API key as the api_key query-string parameter. The base URL depends on your environment and region:

For example, to subscribe a user from the EU production environment:

POST https://api-esp-eu.piano.io/tracker/securesub?api_key=

Always use a key issued for the matching environment — a sandbox key will not authenticate against the production API and vice versa.

Securing the API key

• Treat the key as a credential. Do not commit it to public repositories, post it in tickets that may be shared, or expose it in client-side code.

• Avoid putting the key into URLs that may appear in server logs, analytics tools, or browser history.

• Restrict use of the key to trusted backend processes.

• Rotate the key again whenever you suspect it has been exposed. The previous key is invalidated the moment a new one is generated, so coordinate the rotation with any service that depends on it.

Troubleshooting

If problems persist after verifying the key, key environment, and Site ID, contact Piano Support with the failing request (with the API key redacted) for further investigation.

Last updated: July 02, 2026