Authentication
Create an API key and send it as a Bearer token.
The API uses API keys. Every request must include one in the Authorization header. Requests without a valid key are rejected, and there is no anonymous access.
Create a key
- Sign in to AveeCare.
- Open Settings → API Keys.
- Create a new key, give it a name you will recognise later, and pick its scope.
- Copy the key when it is shown. It starts with
ak_. AveeCare stores only a hash of it, so the full key cannot be shown again. If you lose it, create a new key and revoke the old one.
Scopes
Each key has one of two scopes, chosen when you create it.
| Scope | Allows |
|---|---|
read | GET requests: list and retrieve. |
read + write | Everything in read, plus creating, updating and deleting. |
Calling an endpoint that needs write access with a read-only key returns 403 with the code insufficient_scope. Each endpoint reference page states the scope it needs.
Send the key
Pass the key as a Bearer token.
cURL
curl "https://api.aveecare.com/v1/me" \
-H "Authorization: Bearer $AVEECARE_API_KEY"A quick way to confirm a key works is Retrieve the current API key.
All requests must use HTTPS.
Keep keys safe
- Keep keys on your server. Never ship them in a mobile app, a web page or a public repository.
- Use read-only keys wherever your program does not need to change data.
- Create a separate key for each program so you can revoke one without breaking the others.
- Revoke a key in Settings → API Keys as soon as you suspect it has leaked.
Treat an API key like a password
A key reads and, with write scope, changes your agency's patient data. Anyone holding it can do the same.
When authentication fails
| Status | Code | Cause |
|---|---|---|
| 401 | unauthorized | The key is missing, malformed or revoked. |
| 403 | insufficient_scope | The key is valid but is read-only and the endpoint needs write. |
| 403 | forbidden | The key is valid but is not allowed to perform this action. |
See Errors for the response format.