This article describes how to authorize third-party applications to work with Wild Apricot's Admin API and Member API. You'll learn how to choose the right authentication option, how to get and refresh authentication tokens, and how to use tokens to access the APIs.

Understanding authentication options

You will need an authentication token every time you make a call to Wild Apricot's API. This section explains how to obtain this token.

Authentication tokens are obtained from Wild Apricot's authentication service, which is located at https://oauth.wildapricot.org. This service adheres to oAuth 2.0.

The oAuth 2.0 standard describes several ways to get authenticated. Which way to choose depends on the specific kind of application you want to build.

OptionUse for

API key

Client application provides an API key allowing it to access data.

Server to server integration scenarios, when a client application needs full access to Wild Apricot and does not need the security permissions of the current user.

Examples:
Data synchronization, scheduled reporting, and any other automation that works without any user input.

User login + password

Client application provides the clientId and clientSecret, and also provides the login and password of a Wild Apricot user.

Building client applications which work with Wild Apricot on behalf of the current user. Works well if the user trusts the application and is prepared to enter login and password within the application.

Examples:
Mobile applications that need to access Wild Apricot's API.

Authorization code

Client application redirects the user to a Wild Apricot login page. Works similar to logging in with Facebook.

Building applications which work with Wild Apricot on behalf of the current user. However, users do not have to enter credentials within the application.

Typically, this scheme works for implementing single sign-on scenarios. 

Examples:
Single sign-on for WordPress / Joomla / Discourse

How to obtain authentication tokens

The procedure for obtaining authentication tokens depends on the authentication option you are using.

Using the API key

Use this option for server-to-server integration scenarios, when a client application needs full access to the Wild Apricot system and does not need to have the security permission of the current user.

In order to obtain access token with API key, you have to make the following request:

POST /auth/token HTTP/1.1
Host: oauth.wildapricot.org
Authorization: Basic BASE64_ENCODED("APIKEY:YOUR_API_KEY")
Content-type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=auto

In this template, you should replace the following:

Replace...With...
YOUR_API_KEYAPI key from Authorized applications screen.

Important note:
In this particular case, oAuth service does not return refresh token by default. If you need refresh token when working with API key, add parameter obtain_refresh_token=true

Example:

grant_type=client_credentials&scope=auto&obtain_refresh_token=true

So. finally your request will look like:

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

grant_type=client_credentials&scope=auto

With user’s login and password

Use this option to build client applications that work with Wild Apricot on behalf of the current user. Works well if the user trusts the application and is prepared to enter login and password within the application.

To obtain access token with the user’s login and password, you have to make the following request:

POST /auth/token HTTP/1.1
Host: oauth.wildapricot.org
Authorization: Basic BASE64_ENCODED("CLIENT_ID:CLIENT_SECRET")
Content-type: application/x-www-form-urlencoded

grant_type=password&username=USER_EMAIL&password=USER_PASSWORD&scope=auto

In this template, you should replace the following:

Replace...With...
CLIENT_ID, CLIENT_SECRETValues from Authorized applications screen.
USER_EMAIL, USER_PASSWORDCredentials of user who want to access API.

So finally your request will look like:

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

grant_type=password&username=joe@mail.com&password=pwd123&scope=auto

Using an authorization code

Use this option to build applications that work with Wild Apricot on behalf of the current user but don't require users to enter credentials within the application.

This option is a more secure alternative to the login and password scenario, allowing you to build an app which works with Wild Apricot but does not collect the user’s password.

Typically this scheme works for implementing single sign-on scenarios. 

This is a multi-step authentication procedure:

  1. User opens your application web site.
  2. Your web site redirects the user to a login page on your Wild Apricot site.
  3. User provides their email and Wild Apricot password. 
  4. Wild Apricot checks if credentials are valid and redirects the user back to your website. 
  5. Your website requests a token from the oAuth service.

Before your site redirects the user to the login page, you have to authorize your application on the Authorized applications screen within your Wild Apricot admin view. From this screen, be sure to:

  • Use the User authorization option, so you can obtain a ClientId and a ClientSecret
  • Allow Authorize users via Wild Apricot single sign-on service
  • Add your website to the list of Trusted redirect domains

Now let’s look deeper into each step:

1. User opens your application website

Let’s say your website where your application resides is:
https://mycustomdomain.org.

2. Your website redirects user to Wild Apricot login page

Let’s say your Wild Apricot website is:
https://myorganization.wildapricot.org. 

Your application website should redirect the user to:
https://myorganization.wildapricot.org/sys/login/OAuthLogin

The following parameters should be passed as query string arguments:

ParameterDescription
client_id The identifier of the client application. Obtained when you register the external site as an authorized application.
redirect_uri
URL to which the user will be redirected after login. The URL you specify must be included in the Trusted redirect domains list within the authorized application details.
scope
We recommend setting this value to auto or contacts_me
state
Optional parameter: any value you need to track the request.

So finally you will end up with something like this:

https://myorganization.wildapricot.org/sys/login/OAuthLogin?client_Id=tcRsnqk4mp&scope=auto&redirect_uri=https%3A%2F%2Fmycustomdomain.org%2Fauthcallback&state=1234567
3. User provides email and password 

If you provide valid values, the user will see a page like this:

If the user is already logged into https://myorganization.wildapricot.org, then he will not see this page but will be immediately redirected to the next step.

4. Wild Apricot checks if credentials are valid and redirects the user back to your website 

Wild Apricot redirects the user back to the URL provided in redirect_uri parameter and includes authorization_code and state values as query string arguments.

So your website will get a HTTP request similar to:

https://mycustomdomain.org/authcallback?authorization_code=s98er7gf87sd9fasdf&state=1234567
5. Your website requests a token from oAuth service

Your website should extract the value of authorization_code and use it to get an authentication token from the oAuth service.

To get the token, you have to make the following request:

POST /auth/token HTTP/1.1
Host: oauth.wildapricot.org
Authorization: Basic BASE64_ENCODED("CLIENT_ID:CLIENT_SECRET")
Content-type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTHORIZATION_CODE&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=SCOPE

In this template, you should replace the following:

Replace...With...
CLIENT_ID, CLIENT_SECRETValues from Authorized applications screen.
AUTHORIZATION_CODEValue of authorization_code parameter from query string
REDIRECT_URIThe same value as you provided on step 2
SCOPEThe same value as you provided on step 2

So finally your request will look like:

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

grant_type=authorization_code&code=s98er7gf87sd9fasdf&client_id=tcRsnqk4mp&redirect_uri=https%3A%2F%2Fmycustomdomain.org%2Fauthcallback&state=1234567

oAuth service response

In response to the token request, the oAuth service will return the following:

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"]
      }
   ]
}
ParameterDescription
access_tokenThe value you need to pass to the API
expires_inThe number of seconds the access_token will be valid
refresh_tokenThe token used to refresh the expired access_token
permissionsList of available accounts and allowed operations for this access_token

How to refresh tokens

To refresh the token you have to make the following request:

POST /auth/token HTTP/1.1
Host: oauth.wildapricot.org
Authorization: Basic BASE64_ENCODED("CLIENT_ID:CLIENT_SECRET")
Content-type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN

In this template, you should replace the following:

Replace...With...
CLIENT_ID, CLIENT_SECRETValues from Authorized applications screen.
YOUR_REFRESH_TOKENThe refresh token value returned by the oAuth service

So finally your request will look like:

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

grant_type=refresh_token&refresh_token=bGlvYXUyzZXJsaWtnamxrc2RuZi4=

Working with the API

How does the API know who makes a call?

When Wild Apricot's API gets an HTTP request, it checks the authentication token. If token is not valid or absent, then the API responds with error HTTP 401 Unauthorized.

How to pass auth token to public API?

Authentication token should be passed to the API in Authorization header with Bearer scheme.

Example:

GET /v2.1/accounts HTTP/1.1
Host: api.wildapricot.com
User-Agent: MySampleApplication/0.1
Accept: application/json
Authorization: Bearer YOUR_TOKEN_HERE

Working with API from JavaScript

There is also a special case to allow calls to the API from JavaScript: if your code is located on Wild Apricot site pages (for example, on some page in your_organization.wildapricot.org), then the API calls can be made with the permissions of the currently logged in user. However, your JavaScript code should provide the clientId in a separate HTTP header.

In this case, you don’t need an authentication token, since authentication is based on website session cookie.

Example:

$.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 email:" + data.Email);},
  error: function (jqXHR, textStatus, errorThrown) {
    alert(textStatus + " (" + jqXHR.status + ") : " + errorThrown);}
});