API authentication

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.

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. If you are not an experienced programmer, consider using Make (formerly Integromat) to build automated workflows with Wild Apricot.

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.

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:

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:

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:

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 code and state values as query string arguments.

So your website will get a HTTP request similar to:

https://mycustomdomain.org/authcallback?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:

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"]
      }
   ]
}

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:

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