API Keys
API keys let you use Dashboard.PT programmatically instead of only through the web interface. With a key you can push data into your graphs from your own scripts, read resources, and wire the platform into your applications and automations. This page shows you how to create a key, how to send it to authenticate your requests, and the security practices that keep your account safe.
Overview
An API key is a secret token that identifies your account to the API. Any request that carries a valid key is treated as coming from you, so a key is as sensitive as a password. Each key you create is tied to your account and counts against your plan's API key limit.
What you can do with a key
- Push data into your graphs from external scripts, servers or devices.
- Read resources such as your dashboards, graphs and monitors.
- Automate recurring tasks and integrate Dashboard.PT with other tools.
Creating a key
You manage keys in the Chaves API (API Keys) section of your account.
- Open the API Keys section. Find it in the left sidebar of your account.
- Create a new key. Give it a clear name that says what it is for, such as the integration or server that will use it.
- Copy the key straight away. Store it somewhere safe the moment it is shown — for security the full value may not be displayed again later.
- Use it in your integration. Add the key to the script or service that will call the API.
Note: The number of API keys you can hold is set by your plan (the api_keys limit). If you reach the limit, revoke a key you no longer use before creating a new one.
Authenticating requests
To prove who you are, send your key with every request as an HTTP header rather than in the URL. Keeping it out of the address means it is not logged in browser history, proxies or server access logs.
Send the key as a header
- Add the HTTP header
Authorization: Bearer YOUR_API_KEY. It is the only format the API accepts. - Replace
YOUR_API_KEYwith the value you copied when the key was created. - Never place the key in the query string of the URL.
A request from the command line looks like this:
curl -H "Authorization: Bearer YOUR_API_KEY" https://dashboard.pt/api/...
Security best practices
Because a key grants access to your account, treat it with the same care as a password.
Keep your keys safe
- Keep keys secret. Do not share them in emails, chat messages or screenshots.
- Never commit a key to code or repositories. Store it in an environment variable or a secrets manager, not in source that could be pushed to Git.
- Use a separate key per integration. If one leaks, you can revoke just that key without breaking your other integrations.
- Revoke and rotate. Delete keys you no longer use, and rotate any key you suspect has been exposed.
Details at a glance
| Item | Details |
|---|---|
| Where to manage keys | The API Keys (Chaves API) section of your account |
| How to authenticate | Send the key in an HTTP header, never in the URL |
| How many keys | Set by your plan (the api_keys limit) |
| If a key leaks | Revoke it immediately and create a replacement |
| One key per | Integration, script or service |
Learn more
This page covers how keys are created and sent. For the request and response formats, the available endpoints and how errors are reported, see the related documentation:
- REST API Reference — the available endpoints and what each one does.
- API Requests & Responses — how to structure calls and read the data that comes back.
- API Error Handling — the error codes you may receive and how to react to them.
Managing existing keys
Keys are not just created and forgotten. Reviewing them from time to time keeps your account tidy and secure.
Good housekeeping
- Review your list. Check the keys you hold and confirm each one is still in use.
- Revoke the unused. Delete keys tied to integrations you have retired to free up your plan's allowance.
- Rotate on a schedule. Replacing long-lived keys periodically limits the damage if one is ever exposed without your knowledge.
Tips
Tip: Revoke a key immediately if you suspect it has leaked. Creating a fresh key and updating the affected integration is far cheaper than dealing with unauthorised access.
Tip: Name each key after the integration that uses it. Clear names make it obvious which key to revoke or rotate when something changes.
Want to try it? The free plan has no time limit.
Create a free account