Home Donations Subscriptions Projects Chapters Events Grants Documents People Notifications Treasury

Service Endpoints

Asha Platform API provides RESTful interface for [most of] capabilities. API integration is recommended instead of direct database acess or custom scripts that access/manupilate any data or resources. This page provides the documentation necessary for integrating with the APIs.

  • Service: https://api.ashanet.org/
    This is the endpoint address for accessing/using the APIs. A complete REST operation is performed by combining an HTTP method (or "verb") with a full URI to the resource you're addressing. A comprehensive list of resources is on the left hand navigation menu.
    For example, here's an operation to get a list of all AfE chapters GET https://api.ashanet.org/chapters/all
  • Monitor: https://api.ashanet.org:8443/
  • References: https://developer.ashanet.org/

Authentication & Authorization

Authentication is required for all API operations, and you'll need to set request headers including an access token. To get an access token by using the OAuth client_cedentials token grant type with your api_key:api_secret as BasicAuth credentials.
  • Credentials
    You'll need to work with the webteam to get set of application credentials, a api_key and api_secret, that you havw to use to authenticate your API calls using OAuth Protocol.
  • Acces Token Requests
    With your credentials, you obtain access tokens by sending a requst to /token endpoint. You must authenticate your access token request (uaing HTTP Basic Auth) aith your credentials obrained as described above. The api_key and api_secret becomes your user-id and password in HTTP Basic Auth. See HTTP Basic Authentication for more.

    The OAuth /token endpoint will verify your credentials and returns a scoped access token. The specific kind of token provided is a "Bearer Token" that you should use for any subsequent API calls.
  • API Request Authentication:
    When making the API calls, make request by adding the access token in the "Authorization" header using the following syntax (as defined in OAuth 2.0 Protocol): Authorization: Bearer jhgadsfjhgq457245987245kghdshgsf78.sjhgadf
  • Token Validity & Expiration:
    You must use the access tokens obtained through above steps for making API calls. These tokens have finite lifetime and scope.
    • keep track of expires value in token response. This value is expressed in seconds from the time of access token is generated.
    • handle 401 Unauthorized error response from the API endpoint when an expired token is detected.
    • pay attention to scope in the token response. Scopes can be one or more of ADMIN PAYMENTS TREASURY and describes what resources you have access to. Scopes are tied to your credentials and you'll have to work with the API team to change the scopes for your credentials.


The following headers are mandatory for all API operations:

Accept Always set to application/json
Authentication
  • For OAuth Token requests, always set to Basic your_basic_credentials
  • For all other requests, always set to Bearer your_bearer_token
OAuth Learn more about OAuth Bearer Tokens and how to generate them above.
! api_key and api_secret is privilidged data and must not be shared. If you have more than one applications that you are working with request a different credential pair for each of them.

! If you have have been provided with an access_token, you can send ACCESSTOKEN header with your access_token in the API requests. This is an alternate to OAuth that has been deperecated but available for current applications.

Examples and sources

Once you have the api_key:api_secret you can sart making API calls immediately. You can test with cURL like this:

First, create a OAuth Bearer Token using your application credentials, like this: 
curl -u api_key:api_secret \
-v https://69.64.32.124:8443/token
-H "Content-Type:application/json" \
-H "Authentication: Basic YWZldGVzdGlKdWtTSlllRkJjbTVSOTZ2WlkyblRyMkk4Zm5pMTk4M0FJMHBXalAyMDExOmFmZXRlc3RzbGY3aEdyN3FWS2lJNVdQeHJjUlg3RnpUanFCaTdIMU1tSzRZVGxqMjAxMQ=="
If your credentials are authenticated, you will get a OAuth Authentication Response. The token is a Bearer Token that you should use for any subsequent API calls. Pay attention to the scope that the token is bound to and the expires value that this token is good for. You can re-use the token for multiple API calls that will extend its expiration lese. 
{
  "app": "test-1",
  "scopes": "PAYMENTS TREASURY ADMIN",
  "token": "b2c3c4420ce6c1910212b787ecc7622ab96ea891b54f0b11a003f9c6cd8d947a",
  "expires": 1800
}


Finally, with a OAuth Token at hand, let's make an API call to get all AfE chapters, likt this: 
curl -v https://69.64.32.124:8443/chapters \
-H "Content-Type:application/json" \
-H "Authorization: Bearer b2c3c4420ce6c1910212b787ecc7622ab96ea891b54f0b11a003f9c6cd8d947a"
That's it! really :)
  • PHP - you can use HTTPful (see https://phphttpclient.com/ used by donate.ashanet.org) or cURL (see https://php.net/manual/en/book.curl.php)
  • Node.js - use Unirest (see https://unirest.io/), this is what admin.ashanet.org and workanhour.ashanet.org uses for API integration
  • Python - use Unirest (see https://unirest.io/)