Create an API key
Give your own dashboards, reports and tools access to your workspace through the API, with only the reads and writes each one needs.
An API key lets your own tools use your workspace through the API. Most keys only read: tours, visitors, conversations, leads, follow-ups, and the tour and pulse numbers by date range, to feed a BI dashboard, a warehouse job or a spreadsheet. A key can also write where you allow it, so an agent or script of your own can answer follow-ups, update leads, add knowledge, or edit tours, offers and agent scripts.
A key works on your workspace only. Each key carries the scopes you pick when you create it, so a tool sees and changes only what it needs. New keys start with reads only; writes are off until you turn them on. A developer usually sets up the tool that uses it.
This article covers creating a key, revoking one, and checking a key works.
Before you start
- An admin role in ShowPilot.
- API access on your plan. If your plan doesn't include it, creating a key shows an error saying so.
How do you create a key?
Open API keys
Go to Settings → API keys and select New key.
Name it and choose live or test
In Name, say where the key will be used, like the name of the dashboard or report. Under Mode, choose Live for your real tours, visitors and leads, or Test for a sandbox with sample data, where nothing a tool does touches your workspace.
Pick its scopes
Under Scopes, every read is on to start. Turn off the reads this tool doesn't need, and turn on a write only when the tool must change something, such as Write under Leads for a tool that updates leads. Select Create key.
Copy it now
Select Copy and store the key where your tool keeps secrets. This is the only time ShowPilot shows the full key. If you lose it, revoke it and create another.
The list shows each key's Name, the start of the key, its Scopes, Last used and Status. The Using a key box at the bottom links to the developer docs, where every endpoint is described.
How do you revoke a key?
Select Revoke next to the key and confirm. It stops working immediately. Anything still using it gets an authentication error until you give it a new key. Revoked keys stay in the list, marked Revoked.
Test it
A key is working when ShowPilot records it being used:
- Have your tool make one request with the new key.
- Reload Settings → API keys. The key's Last used date shows today.
Troubleshooting
| Issue | What to check |
|---|---|
| Creating a key shows an error | Your plan may not include API access. The error says so when that's the reason. |
| Your tool gets an authentication error | The key may have been revoked. Check its Status, and create a new key if it shows Revoked. |
| Your tool gets a permission error on one endpoint | That endpoint's scope is turned off on the key. Create a key with the scope turned on. A change needs the Write scope, not only Read. |
| Your tool's changes don't show up in ShowPilot | The key may be a Test key, which works in a sandbox. Check for the Test label next to its name, and create a Live key. |
| You lost the full key | ShowPilot shows it only once. Revoke it and create another. |
Frequently asked questions
Can a key change anything in ShowPilot?
Only where you allow it. New keys start with reads only, and a key can change something only when you turned on that kind of data's Write scope. A key never reaches another workspace.
What are scopes?
Each scope covers one kind of data, such as tours or conversations, and one kind of access, such as Read or Write. A key only answers requests for the scopes it carries, so a reporting tool doesn't need to see conversations, and a dashboard never needs a write.
What date ranges can I request?
Ranges are whole days, up to a year. With no range, a request returns the last 30 days.
Should several tools share one key?
Use one key per tool. Separate keys let you revoke one tool's access without breaking the others.