Setup
API keys and API usage
Give each connected app its own API key with only the scopes it needs, cap its request rate, rotate its secret without downtime and watch its requests on the API usage page.
An API key lets one of your other systems, such as a reporting tool or a referral portal, call the NeatPractice API for your clinic. Give each app its own key: it then carries only the scopes that app needs, its own request limit and its own line on the usage page. API keys are part of plans that include API access. Open Setup, then API Keys under Integrations.
Create a key#
- Click New API Key.
- Enter a Name that says which app uses it, such as
Referral portal sync. - Tick the Scopes the app needs. Each resource has its own read and write scopes; a write scope does not include reading, so tick both when the app does both.
- Optionally set an expiry date, or turn on Own rate limit and enter the most requests per minute this app may send.
- Click Create, then copy the key. It is shown only once; store it in the app's settings.
The app sends the key in an X-Api-Key header on every request. A request for something its scopes do not cover is
refused, and the refusal names the scope it would need.
Scopes#
| Scope | What it allows |
|---|---|
organization:read | Read your organization |
users:read | Read your users |
reports:feed | Read the reporting data feed |
webhooks:read | List your webhook endpoints |
webhooks:write | Add and remove webhook endpoints, so an app can subscribe itself to webhooks |
Rate limits#
Without its own limit, a key shares your plan's request limit with your other keys. With Own rate limit, the key
gets a separate window of the number of requests per minute you set (1 to 6,000), so one busy app cannot use up the
limit the others need. A request over the limit is refused with status 429 and a Retry-After header saying how many
seconds to wait.
Rotate a key#
Rotate a key when it may have been exposed, or on a schedule. Choose Rotate Key from the key's actions, pick how long the old key keeps working (right away, 1 hour, 24 hours or 7 days) and click Rotate. Copy the new key and put it in the app before the old one stops. The key keeps its name, scopes, limit and usage history. While the old key still works, the list shows when it stops.
Turn off or delete a key#
Edit the key and turn it off to stop it at once; turn it back on later if needed. Delete removes the key for good. Its past requests stay on the usage page.
API usage#
Setup, API Usage shows the requests your keys made over the last 7, 30 or 90 days:
- Requests, Errors (answers of 400 or above) and Rate limited (answers of
429) for the period. - By day: requests and errors each day.
- By key: each key's requests, errors, rate-limited requests, its own limit and when it last called.
- By endpoint: the busiest operations, shown as the route the app called (for example
GET webhook-endpoints), never with record ids, search terms or request contents. - By status: how many requests ended with each status code.
Pick a key at the top to see one app alone.