API v1.1

OAuth2

Starting from v1.1, authentication with the Stiply API will be through OAuth2 (https://oauth.net/2/). A full treatment of the OAuth2 protocol is beyond the scope of this article. Instead, the primary goal is to discuss what you need to do in order to work with OAuth2 in the context of the Stiply API.

Aside from the addition of all OAuth related routes, calling the Stiply API has not changed. You can use https://www.stiply.nl/api as a reference for building an integration: the end-points are the same in v1.1.

Setup

First off, in order to connect with the Stiply API through OAuth you will need an account for which API access is enabled. Once this is done you will see an “API settings” item in the “Account” section of the right-top dropdown menu in the Stiply app:

Selecting this menu item will redirect you to a page where you can configure several API related settings[1]. Specifically, the OAuth section will look something like:

Stiply offers two ways to use OAuth. The first one is the recommended, but also the most involved way to authenticate with the API. The second one is easier, but also less flexible and potentially less secure and is only really meant to be used for testing and experimentation purposes[2]. We will first discuss the second option.

Personal Access Tokens

To create a new personal access token, simply click the “Create New Token” link. This will open a modal where you can enter the name of your new token:

After clicking the “Create” button you will receive a new personal access token:

This will be the only time it will be shown to you, so store it somewhere safely and don’t lose it. The token can now be used to make your requests to the Stiply API (see the Authentication section below). The token is valid for one month. Once it expires it can no longer be used to authenticate with the API and you will have to generate a new personal access token in order to do so.

Authorisation Code Grant

Although a personal access token is an easy way to connect with the Stiply API, the recommended way is by means of the authorisation code grant. This is a bit more involved and hence, we will discuss it in some detail.

In order to describe the authorisation redirect flow we will assume you have a consumer or client app. This app will be responsible for initiating and further handling of the authorisation redirect procedure that is at the base of OAuth2[3].

The first step is to create a new OAuth client using the API settings page of the Stiply app:

The name of your client could essentially be anything, but ideally would be something your users will recognise and trust. The redirect URL field is where you will be redirected to after your user accepts your authorisation request[4]. Once successfully created, you will see a new entry in the OAuth clients table:

You can edit the details of this client or delete it if you no longer need it.

Now that you have registered a client with Stiply you can go ahead and reference it in your consumer app (i.e. your app that is consuming Stiply’s OAuth authentication services) in order to request an access token. The examples are written in PHP[5], but should be easy enough to adapt to your own personal use case.

First off, the consuming application should make the following redirect request:

Route::get('/redirect', function (\Illuminate\Http\Request $request) { // Optional, but recommended; protection against XSRF 

 $request->session()->put('state', $state = \Illuminate\Support\Str::random(40)); // Build the query parameter string to pass auth information to our request 

 $query = http_build_query([ 'client_id' => 'my-client-id', 'redirect_uri' => 'http://consumer.test/callback', 'response_type' => 'code', 'state' => $state, ]);

 // Redirect the user to the OAuth authorisation page
 return redirect('https://app.stiply.nl/oauth/authorize?'.$query);
});

There are a couple of things to note here. As you can see, the “client_id” parameter is equal to the client id of the OAuth client we previously created in the Stiply app and the “redirect_uri” parameter is equal to the redirect URL field we specified when creating the client. Lastly, note that the root of the URL of our authorisation request is https://app.stiply.nl (i.e. the URL of the Stiply app not the API).

In response to this redirect request, and assuming the user is logged out of the Stiply app, the user will be redirected to the Stiply login page. After log in the user will be presented with the following view:

Clicking on the “Authorize” button then will redirect the user to your callback URL which in turn must be used to request the first access and refresh tokens:

// Route that user is forwarded back to after approving on server
Route::get('/callback', function (\Illuminate\Http\Request $request) {

 $state = $request->session()->pull('state');
    
 // If state parameters are different, someone else has initiated the request
 throw_unless(strlen($state) > 0 && $state === $request->state,\InvalidArgumentException::class);

 $http = new \GuzzleHttp\Client;

 $response = $http->post('https://app.stiply.nl/oauth/token', [
 'form_params' => [
  'grant_type' => 'authorization_code',
  'client_id' => 'my-client-id',
  'client_secret' => 'my-client-secret',
  'redirect_uri' => 'http://consumer.test/callback',
  'code' => $request->code, // Get authorisation code from the callback
  ],
 ]);

 // echo the response; normally we would save the access and refresh tokens in the DB
 return json_decode((string)$response->getBody(), true);
});

This will return a JSON response with the following content:

{
 "token_type": "Bearer",
 "expires_in": 1800,
 "access_token": "{accessToken}",
 "refresh_token": "{refreshToken}"
}

The access token can now be used to make your requests to the Stiply API (see the [Authentication](#authentiction) section). The access token is valid for 30 minutes. Once it expires you can use the refresh token to request a new access token:

// Route that may be used to request a new access token, using the refresh token
Route::get('/refresh_token', function () {
 $http = new \GuzzleHttp\Client;

 $response = $http->post('https://app.stiply.nl/oauth/token', [
  'form_params' => [
   'grant_type' => 'refresh_token',
   'refresh_token' => '{refreshToken}',
   'client_id' => 'my-client-id',
   'client_secret' => 'my-client-secret',
  ],
 ]);

 return json_decode((string) $response->getBody(), true);
});

This again will return a response of the form:

{
 "token_type": "Bearer",
 "expires_in": 1800,
 "access_token": "{accessToken}",
 "refresh_token": "{refreshToken}"
}

containing a new access and refresh token. Note that refresh tokens are valid for 60 minutes. Once they expire the user will have to restart the OAuth redirect procedure from the beginning.

In summary

1. Once a client has been created, you may use the client ID and secret to request an authorisation code from your application
2. Once the authorisation request has been approved the user will be redirected to your OAuth callback route from which you may now make a request to obtain your first access token using the authorisation code that is send along with your callback URL as a query parameter.
3. Once you have obtained your first access token you can use it to make requests to the Stiply API. Access tokens are valid for 30 minutes. Once they expire you can use the refresh token to request a new access (and refresh token). Refresh tokens are valid for 60 minutes, after which you will have to restart the authorisation redirect procedure from the beginning.

Authentication

Once you have obtained an access token, using either of the two previously discussed methods of generating such a token, authentication with the Stiply API is straightforward. Simply add a header to your request named “Authorization” and set its value equal to “Bearer YOUR_ACCESS_TOKEN”, where “YOUR_ACCESS_TOKEN” is the access token you either received in your callback or refresh token route in case of the authorisation code grant, or was displayed to you in the Stiply app after creating a new personal access token. An example in Postman:

Note that the URL for making API requests using an access token is the URL of the Stiply API not the Stiply app and that all routes should be prefixed with v1.1 instead of v1.

1: Currently, the only settings you can configure are purely OAuth related and hence, this tab will be selected by default.

2: It may also serve as a simpler approach to connect with the API, as it avoids the typical OAuth2 authorisation code redirect flow, but this is not recommended.

3: We assume you are already familiar with OAuth2 terminology and concepts that can, for instance, be found here: https://oauth2.thephpleague.com/terminology.

4: The root URL used here is purely for local test purposes. Hence the reason it starts with “http” and utilises the “.test” domain. In a more realistic setting it would rather look something like https://consumer.com.

5: Laravel to be exact, also see this for reference.