Home

Download this help site
(PDF 82MB)

Download

Authenticating API access from a 3rd-party server or application

Icon

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.

Each Wild Apricot API call must include authentication information that  verifies  your account and prevents others from accessing your data. The required authentication information – and how it is passed – differs depending on whether you are accessing the API from a 3rd party server or application, or from a Wild Apricot site page. For more information on access options, see API access options. For information on authenticating from a Wild Apricot site page, see Authenticating API access from a Wild Apricot site page

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. 

Icon

If you've previously generated an API key for your account – prior to the 5.4 release – it will automatically be converted to an authorized application called Legacy API key.

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:

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.

Parameters 

Variable

Description

grant_type

Must be set to client_credentials .

scope

The functional areas that can be accessed. Multiple scopes must be separated by spaces. Click here for a list of supported scopes.

Example

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

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:  

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.  

Parameters   

Variable

Description

grant_type

Must be set to password.

usernameThe username of the Wild Apricot user.
passwordThe password of the Wild Apricot user.
scope

The functional areas that can be accessed. Multiple scopes must be separated by spaces. Click here for a list of supported scopes.

Example  

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

Authorization response

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

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:

AreaDescription
autoMaximum 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_editModify contact details.
contacts_meView user's own contact details.
contacts_viewView contact details.
event_registrations_editModify event registrations.
event_registrations_viewView event registrations.
events_viewView event details.
finances_editModify invoices, payments, payment allocations, and tenders.
finances_viewView invoices, payments, payment allocations, and tenders.
membership_levels_viewView membership levels.
accountObsolete. Replaced by account_view (see above)
contactsObsolete. Replaced by contacts_view and contacts_edit (see above)
financesObsolete. Replaced by finances_view and finances_edit (see above)
eventsObsolete. Replaced by events_view (see above)
event_registrationsObsolete. Replaced by event_registrations_view and event_registrations_edit (see above)
membership_levelsObsolete. Replaced by membership_levels_view (see above)
Icon

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:

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:

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:

Variable

Description

grant_type

Must be set to refresh_token

refresh_token The refresh_token from the authorization response

Example

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.

The following request deletes the existing 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.

Parameters 

 

Variable

Description

token

Valid authentication token

accountID

Wild Apricot account ID

passwordNew password

Example

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.

On this page:  

  • No labels