Skip to main content
Userpilot APIs use API keys to authenticate requests. You create and manage your API keys on the API keys tab of the Environment page in your Userpilot dashboard.

How to use your API key

Include your API key in the Authorization header of every API request:
Your API key carries many privileges. Keep it secure and do not share it in publicly accessible areas.
All API requests must be made over HTTPS.

Create an API key

Each key belongs to one environment, production or staging, and works only for that environment. To create a key:
  1. In your Userpilot dashboard, go to Environment > API keys, or open the API keys tab directly.
  2. Click Create API key.
  3. Enter a Name that tells you where the key is used, for example “Backend integration”. Names can be up to 60 characters.
  4. Select the Environment for the key.
  5. Click Create key, then copy the key.
  6. Store the key somewhere safe, select I’ve copied and stored this key, and click Done.
The full key is shown only once, when you create it. After that, the API keys tab shows only the first characters of the key. If you lose a key, create a new one.
You need permission to manage environments to open the API keys tab. If you don’t see the tab, ask an admin of your Userpilot account.

Manage your API keys

The API keys tab lists the keys of both environments, with who created each key and when, and who deactivated it and when. You can search keys by name and filter them by environment and status. Open the actions menu of a key to change it:
  • Deactivate: Requests that use the key stop working with 401 Unauthorized. The key stays in the list, and you can re-activate it later.
  • Re-activate: The key works again.
  • Delete: Removes a deactivated key permanently. You can delete a key 30 seconds after you deactivate it. To confirm, type the name of the key. A deleted key can’t be re-activated.
Each environment can have up to 10 active keys. To create or re-activate a key when an environment already has 10 active keys, deactivate one of them first.

Rotate an API key

To replace a key without downtime:
  1. Create a new key for the same environment.
  2. Update your integration to use the new key.
  3. Deactivate the old key, and check that your integration still works.
  4. Delete the old key.
If you suspect that a key has been compromised, deactivate it right away, then create a new key for your integration.

Security best practices

  • Never expose your API key in client-side code or public repositories.
  • Use a separate key for each integration, so you can deactivate one without affecting the others.
  • Rotate your API keys regularly.
  • Deactivate keys you no longer use.