Authentication
The Donorfy API supports two authentication methods:
- System authentication (HTTP Basic) — for integrations and system-to-system access. This is the method third-party integrators should use, and it is described below.
- Access Identity (JWT bearer) — for interactive Access users signing in through the Access platform. See Access Identity at the end of this page.
System authentication (Basic)
Every request must include two headers:
| Header | Value |
|---|---|
X-API-Key | Your tenant code |
Authorization | Standard HTTP Basic credentials |
The Basic credentials are your permission name as the username and your
access key as the password. The X-API-Key header tells the API which
tenant the request is for. Most HTTP clients will build the Authorization
header for you when you supply a username and password.
Where to get your credentials
API credentials are managed by a tenant administrator inside Donorfy, under Settings → Configuration, selecting API Settings from the dropdown. From there you can create or review an API access record, which gives you:
- the tenant code to send in
X-API-Key, - a permission name (the Basic auth username), and
- an access key (the Basic auth password).
Treat the access key as a secret: store it securely, never embed it in client-side code, and rotate it if it may have been exposed.
Restricting access by IP address
An API access record can optionally be restricted to a range of caller IP addresses, configured alongside the credentials in API Settings. When a range is set, requests from outside it are rejected even if the credentials are valid. Leave the range empty to allow calls from any address.
Access to specific endpoints depends on the permissions granted to the
credentials you use. If a request returns 403 Forbidden, check that your
permission has the rights required for that operation.
Example request
Replace the placeholder values below with your own. Do not commit real credentials to source control.
curl --request GET \
--url 'https://api.donorfy.npe.accessacloud.com/v1/constituents' \
--header 'X-API-Key: <your-tenant-code>' \
--user '<your-permission-name>:<your-access-key>'
If either header is missing or the credentials are invalid, the API responds
with 401 Unauthorized. See Errors & responses
for the full list of status codes.
Access Identity (JWT)
The API also accepts Access Identity bearer tokens for interactive Access users signing in through the Access platform. Requests are then made on behalf of that signed-in user, and their Donorfy role determines what they can do.
If you are building a third-party integration you should use System authentication described above, which is the supported path for machine-to-machine access.