Follow

API access options

Wild Apricot's API supports access from a 3rd party server or application, or from a Wild Apricot site page.

Wild Apricot's API is intended for use by developers with technical expertise. If you need assistance, we provide support via email or through our Developers forum.

Wild Apricot's API supports access from a 3rd party server or application, or from a Wild Apricot site page.

From 3rd party server/application

Using Wild Apricot API calls, a 3rd-party server or application can retrieve, display, and update information stored in your Wild Apricot database.

The same base API address – https://api.wildapricot.org/ – is used for calls from 3rd-party servers and applications, including those placed by mobile applications. A Base API call will retrieve a list of API versions. If you add the version number to the base API call, a list of top-level API calls will be returned.

Only encrypted HTTP requests – ones that begin with https – are supported for calls from 3rd-party servers or applications. Insecure requests – ones that begin with http – are not supported.

Each Wild Apricot API call must include authentication information that verifies your account and prevents others from accessing your data.

With Wild Apricot's API, server-side authentication is a two-step process. In the first step, the client application requests an authentication token from the authentication server. In the second step, the authentication server returns an authentication token, which the client application uses in the API call.

Wild Apricot API uses the OAuth authentication standard and issues OAuth authentication tokens. Wild Apricot's authentication tokens are valid for a limited period of time. You can send a request to the authentication server to refresh the token after it has expired.

You can also use the authentication server to log out, and to change your password.

Authorizing your application

When accessing Wild Apricot's API, an 3rd-party server or application must first be authorized to access your Wild Apricot account. During authorization, the application will be assigned a unique API key. If the application provides account access to individual users (via a mobile app, for example), the application can be assigned a client ID and a client secret as well.

To authorize a server or application to access your Wild Apricot account, follow these steps:

  1. Hover over the Settings menu and select the Security option.
  2. Within the Security settings screen, select the Authorized applications option.
  3. Within the Application authorization screen, click the Server application option if your application does not provide account access to individual users, or Users authorization if it does. Then, click the Continue button.
  4. From the Application details screen, copy the API key. If there is no API key displayed, click the Generate API key button.
  5. Choose whether you want the application to have read-only access or full access to your Wild Apricot account. If you choose read-only access – and request an authentication token using the API key – then only those functions represented by scopes that ends with _view (see below) will be accessible to your application.
  6. If your application provides account access to Wild Apricot users, copy the Client ID and Client secret values. If there is no Client secret value displayed, click the Generate client secret button.
  7. If your application provides account access to users, choose whether to authenticate users via Wild Apricot's single sign-on screen. If you disable this option, the application can still access data in your Wild Apricot account, but users will not be logged in their Wild Apricot accounts within their browser.
  8. If you enable single sign-on, you can also specify the organization name and introductory text to be displayed on the single sign-on screen, and whether to allow users to log in using their Facebook or Google+ credentials ..
  9. Click the Save button to save your changes.

Requesting the authentication token

There are three methods you can use to request the authentication token you need to include in the Wild Apricot call. You can use:

  • the application's API key
  • Wild Apricot user credentials
  • the authorization code returned by Wild Apricot's single sign-on service

For information on using the authorization code for authentication, see Single sign-on service. For information on using the application API key and Wild Apricot user credentials, see below.

Using the application's API key

To request an authentication token using your application's API key, you pass the key in the authorization header. Within the authorization header, the authorization type must be Basic, and the credentials must be delimited by a colon ( : ) and encoded in base64. The credentials use the following syntax:

username:password

where username equals APIKEY and password is the API key assigned when the application was authorized.

The client application should keep the API key secret and provide it only to https://oauth.wildapricot.org/auth/token and only over HTTPS with a valid certificate.

The request body must provide the following parameters using the application/x-www-form-urlencoded format with a character encoding of UTF-8 in the HTTP request entity-body.

  • grant_type
    Must be set to client_credentials .
  • scope
    The functional areas that can be accessed. Multiple scopes must be separated by spaces. See below for a list of supported scopes.

In this example, the client application makes the HTTP request over https:

   POST /auth/token HTTP/1.1
Host: oauth.wildapricot.org
Authorization: Basic MTIzOnJrdHVkN2FucW91aWJ0ZG0xZDR5aG9iOWRneQ==
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=contacts finances events
Using Wild Apricot user credentials

You can request authentication using the credentials of any Wild Apricot user, whether an account administrator or not.

To request an authentication token using Wild Apricot user credentials, you pass the client ID and client secret – assigned when the application was authorized – in the authorization header. Within the authorization header, the authorization type must be Basic, and the credentials must be delimited by a colon ( : ) and encoded in base64. The credentials use the following syntax:

username:password

where username is the client ID and password is the client secret assigned when the application was authorized.

The client application should keep the client credentials secret and provide it only to https://oauth.wildapricot.org/auth/token and only over HTTPS with a valid certificate.

The credentials of the Wild Apricot user are passed within the request body. The request body must provide the following parameters using the application/x-www-form-urlencoded format with a character encoding of UTF-8 in the HTTP request entity-body.

  • grant_type
    Must be set to password.
  • username
    The username of the Wild Apricot user.
  • password
    The password of the Wild Apricot user.
  • scope
    The functional areas that can be accessed. Multiple scopes must be separated by spaces. See below for a list of supported scopes.

In this example, the client application makes the HTTP request over https:

   POST /auth/token HTTP/1.1
Host: oauth.wildapricot.org
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=johndoe@gmail.com&password=123456&scope=contacts finances events

After receiving the authentication request, the authorization server authenticates the client application and validates the API key, and if valid, issues an access token.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"Bearer",
"expires_in":1800,
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
"permissions":[
{
accountId:123,
availableScopes:["contacts_view", "contacts_me", "contacts_edit", "finances_view", "events_view"]
}
]
}

In this example:

  • access_token is the token, which can be used to access the API.
  • token_type is a type of authorization token. Currently Wild Apricot's API supports only the Bearer token type.
  • expires_in is the number of seconds the access token is valid for. By default, Wild Apricot's API expires after 1800 seconds (30 minutes). After the time has elapsed, the token expires and cannot be used to access the API. You can, however, refresh the token.
  • refresh_token is a token, which is used to refresh the access token.
  • permissions is a collection of available scopes for each account, where accountId is the account number.

If the request is not valid, an error description will be returned.

Supported scopes

As part of the authentication request, you can specify the scope – the functional areas that can be accessed by the application. Multiple scopes must be separated by spaces. The following scope values can be used:

  • auto
    Maximum allowed scope is automatically detected. When authenticating using the API key, the maximum scope depends on the API key access level set when authorizing the application. When authenticating with user credentials, the maximum scope is derived from the user's Wild Apricot account permissions.
  • account_view
    View account information.
  • contacts_edit
    Modify contact details.
  • contacts_me
    View user's own contact details.
  • contacts_view
    View contact details.
  • event_registrations_edit
    Modify event registrations.
  • event_registrations_view
    View event registrations.
  • events_view
    View event details.
  • finances_edit
    Modify invoices, payments, payment allocations, and tenders.
  • finances_view
    View invoices, payments, payment allocations, and tenders.
  • membership_levels_view
    View membership levels.
  • account
    Obsolete. Replaced by account_view (see above)
  • contacts
    Obsolete. Replaced by contacts_view and contacts_edit (see above)
  • finances
    Obsolete. Replaced by finances_view and finances_edit (see above)
  • events
    Obsolete. Replaced by events_view (see above)
  • event_registrations
    Obsolete. Replaced by event_registrations_view and event_registrations_edit (see above)
  • membership_levels
    Obsolete. Replaced by membership_levels_view (see above)
Obsolete scopes within existing code will be automatically substituted.

Using the authentication token

Any request to Wild Apricot's API must include the authorization token in the HTTP header. The header should contain the token type and the authorization token, delimited by a space. The only supported token type is Bearer.

Below is a sample API call, including the authorization token:

GET /v2/accounts HTTP/1.1
Host: api.wildapricot.org
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

If the authorization token is invalid or expired, then a status code of 401 will be returned, and the response body will include a reason field. Below is a sample JSON response to an invalid token:

{
reason:”invalid_token”
}

Refreshing the token

If an access token is expired, the client application can make a refresh request to the authentication server, providing the following parameters using the application/x-www-form-urlencoded format with a character encoding of UTF-8 in the HTTP request entity-body:

grant_type
Must be set to refresh_token

refresh_token
The refresh_token from the authorization response

Example
   POST /auth/token HTTP/1.1
Host: oauth.wildapricot.org
Authorization: Basic MTIzOnJrdHVkN2FucW91aWJ0ZG0xZDR5aG9iOWRneQ==
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

Expiring a token

Authorization tokens automatically expire after a certain period of time. You can, however expire a token before that time. If you do so, you should also delete the refresh token.

The following request expires an existing token.

GET https://oauth.wildapricot.org/auth/expiretoken?token={oauth_token}

The following request deletes the existing refresh token.

GET https://oauth.wildapricot.org/auth/deleterefreshtoken?refreshToken={oauth_refresh_token}

There is no response from the server in either case.

Changing passwords

If you requested the authorization token using administrator account credentials, you can use the authorization server to change your account password. To change your password, make a POST request to https://oauth.wildapricot.org/auth/password, using the following parameters.

  • token
    Valid authentication token
  • accountID
    Wild Apricot account ID
  • password
    New password
Example
POST https://oauth.wildapricot.org/auth/password
{
"Token":"ma4owieutrlvajsdfja34mo2jmwej",
"AccountId":123,
"Password":"newPassword123"
}
Response fields

If password is successfully changed, the API returns HTTP 200 OK and no data in response body. If password change fails, the API returns an error field describing the error.

From a Wild Apricot site page

Using Wild Apricot's API, you can embed JavaScript code in your Wild Apricot site pages that uses API calls to retrieve, display, and update Wild Apricot database information. Within each API call, you must include authorization information that verifies your account and prevents others from accessing your data. Specifically, you must include the client ID that is generated when you authorize your application.

Authorizing your application

Even though JavaScript within a site page does not constitute a separate application, you must authorize an application to generate the client ID required to verify your account and prevent unauthorized access to your Wild Apricot data.

To authorize an application for access to your Wild Apricot account, follow these steps:

  1. Hover over the Settings menu and select the Security option.
  2. Within the Security settings screen, select the Authorized applications option.
  3. Within the Application authorization screen, click the User authorization option then click the Continue button.
  4. From the Application details screen, copy the Client ID value. This is the value you must pass within your API calls.
  5. Click the Save button to save your changes.

Accessing the API

An account-specific URL is used to access Wild Apricot's API from Wild Apricot site pages:

http://your_account_url/sys/api/

where your_account_url is your Wild Apricot domain name.

When accessing the account-specific URL using JavaScript, the protocol should match the protocol currently being used by the browser, so the best choice is to use relative URLs in the API call.

For example, instead of:

http://stevelivetestsite.wildapricot.org/sys/api/v2/accounts/58293/contacts/me 

you would use:

/sys/api/v2/accounts/58293/contacts/me

Passing authorization information

Each API call made from within a Wild Apricot site page must include the client ID value that is generated when you authorize your application (see above). The authorization information verifies your account and prevents others from accessing your data.

Within your JavaScript, the client ID should be passed in the HTTP header, using the following format:

clientId: APPLICATION_CLIENT_ID

For example, within jQuery code, the call might appear as follows:

<script>
$(document).ready(function(){
$.ajax(
{
url: "/sys/api/v2/accounts/58293/contacts/me",
type: "GET",
dataType: "json",
cache: false,
async: true,
headers: { "clientId": "APPLICATION_CLIENT_ID" },
success: function (data, textStatus, jqXhr) {
alert("Current contact id:" + data.Id + ". Contact email:" + data.Email);},
error: function (jqXHR, textStatus, errorThrown) {
alert(textStatus + " (" + jqXHR.status + ") : " + errorThrown);}
});
});
</script>

Access to Wild Apricot data will be limited by the access permissions of the currently authenticated user. Consequently, the API cannot be accessed within public pages that do not require user authentication.

All Wild Apricot API calls must also include the account number – 58293 in the above examples – that is returned by the Accounts API call.

Comparing access options

The following summarizes the differences between the two access options.

3rd-party server/application

  • Base API address: https://api.wildapricot.org
  • Supported protocols: HTTPS
  • Access permissions: Depends on authentication method
  • Accessed from: External server/application
  • Sample uses: Server-to-server scenarios, mobile/desktop applications

Wild Apricot site page

  • Base API address: http://your_account_url/sys/api/
    where your_account_url is your Wild Apricot domain name
  • Supported protocols: HTTP, HTTPS
  • Access permissions: Those of the currently authenticated user
  • Accessed from: Wild Apricot site page
  • Sample uses: Use JavaScript for custom display of Wild Apricot data

0 Comments

Please sign in to leave a comment.

Search: WildApricot.com 

About results ( seconds) Sort by: 
Sorry, an error occured when performing search.