Authentication Types

Authentication of users and applications to the Willow API is done via OAuth 2.0 endpoints. To access the Willow API, you'll need to retreive an access token.

Getting Started with OAuth 2.0

OAuth 2.0 is a protocol that allows third-party applications to authenticate with APIs. OAuth 2.0 facilitates two main actions - obtaining an access token through user or application authorization, and using that access token to make API requests. At the end of a successful OAuth exchange, an access token with a expiration time is returned to your application. You will need to submit this token with each Willow API request in order to properly identify your application and access data in a secure manner. The access token includes scopes, or permissions, which determines how your app is able to interact with the Willow platform.

If you are new to OAuth 2.0, we recommend reviewing the following documentation:

• OAuth 2.0 Standard
• OAuth Simplified by Aaron Parecki

Choosing an OAuth 2.0 Grant Type

The first step in building an app is selecting the proper OAuth2.0 authorization grant type for your application. The grant type determines the flow that will be used to obtain an access token. Typically, the grant type will be determined by the type of application you are building. Here is an overview of the OAuth 2.0 grant types supported by the Willow API.

Client Credentials Grant (Machine-to-Machine, userless)

If you are developing a backend service application that needs to authenticate directly with the Willow platform, the Client Credentials Grant should be used. In this scenario, an individual user is not required to grant authorization. This grant type is often referred to as machine-to-machine and should be used when the client is confidential.

Here is a diagram illustrating the Client Credentials flow and the associated steps involved:

1. Your application requests an access token from the Willow Authentication Endpoint using the Client ID and Client Secret credentials provided to you during your developer onboarding. The JSON payload for this request is as follows:

{
    "client_id": "<YOUR_CLIENT_ID>",
    "client_secret": "<YOUR_CLIENT_SECRET>",
    "grant_type": "client_credentials"
}

2. The Willow Authentication Endpoint returns a JSON response that includes the accessToken and other supporting data.

{
    "token_type": "Bearer",
    "expires_in": 3599,
    "ext_expires_in": 3599,
    "access_token": "<YOUR_ACCESS_TOKEN>"
}

3. Your application can now use the access token to make calls to the Willow API.

Authorization Code (Web Server Apps)

If you are developing a web server or mobile application that requires the user to authenticate with the Willow platform, the Authorization Code Grant should be used.

This is not currently supported by the Willow API, but please contact us if you have an application that requires this authorization flow.