RaiseDonors allows 2nd parties (the organization) to utilize an API to manage aspects of the data within RaiseDonors. This document will be a guide on how to set up access to consume the API and then how to make calls to the API to manage certain types of data.
Setting up the organization to be able to consume the API requires a couple steps to setup an application and access for that application. It is possible to create API applications that only have read access to the data while others have Read/Write access.
Once logged in to RaiseDonors, go to the API menu section and click on applications. This is where the applications can be viewed and managed.
An application is a container that will hold multiple API license keys for read/write consumption of the API. It allows the consumer to be secure in the API calls that are made. It also allows RaiseDonors to keep metrics on the applications that are hitting the API -- which is particularly powerful in case malicious activity occurs.
API applications are created to organize the different applications that the organization is developing that will be consuming the API.
- In the menu is a section for the API. Here you will find all the navigation concerning the API.
- The organization key is important. It is necessary for the RaiseDonors API to identify the organization the request is for. The organization key will be passed with each request in the headers with the header name "X-OrganizationKey"
- The list of applications that have been created by the organization. Clicking on an application name will display the details about that application.
- To create a new application, click the "+New Application" button.
Create New Application
Creating a new API application consists of a title, a description and an indicator for if the API application is Active. It is possible to disable an application without deleting it.
- Name each API application a unique name that quickly describes the application that is being built that will consume the API.
- Toggle whether the API application is active or not. If the API application is active, then the API keys that make up that application will be able to be used for API requests.
- The description allows for a more robust explanation of the purpose of the API application.
- Click the "Save application" button when all information is filled out.
When an API application is not active, the API license keys for that application will not be able to be used for API requests.
Manage API Application
When an API application is created and either (1) needs to be viewed or (2) license keys need to be managed for the API application: clicking the name of the API application from the "Applications" screen will show the details of the API application.
Managing the API application will allow for the editing of the details of the application, managing the API license keys for that application, and the ability to delete the API application.
- Edit the details of the API application (Name, description and whether it is active) by clicking "Edit Details".
- The list of application license keys are shown here. The license key is necessary for all API requests.
- New license keys can be created by clicking "+ New License Key"
- Delete an API application by clicking "Delete".
When an application is deleted, all license keys become revoked. At that point no license keys for that application will be able to be used for API requests.
API License Keys
API license keys are what tell the API what data can be consumed and in what fashion. Creating multiple API license keys is beneficial as the license key itself can be revoked. Allowing for some API keys to be read only while some having the ability to write from the API will narrow the scope of each API license key.
- Name the license key something unique that easily identifies the purpose of the API license key.
- Identify if the license key is to be used for only reading data or if the license key has the ability to write data to the API.
- Save the API key by clicking "Save API key".
- When editing the license key, there is the ability to revoke the license key. Revoke the license key by clicking "Revoke API key".
If an API license key is revoked, it can no longer be used with the RaiseDonors API. Revoking a license key cannot be undone.