Authorization code flow

Overview

The Authorization Code Flow is a more complex scheme to implement than Client Credentials but is better suited to letting a web application connect to Trelica, whilst letting end-users control what access that application is given to Trelica data.

The basic steps are as follows:

1. User clicks 'Connect to Trelica' button in your web application.
2. Your web application redirects the user's browser to the Trelica /connect/authorize URL.
3. The user then logs in to Trelica and sees a screen which tells them that your application is requesting access to Trelica, and the sort of Trelica data your application wants access to.
4. Trelica redirects the user's browser back to a page in your web application, appending an authorization code (if access was granted)
5. Your web application swaps this authorization code for a Trelica access token.
6. Your web application then communicates to the user that the connection was successful.

Authentication

As you will from steps 2 and 5 above, there are two Trelica end-points that are needed to support OAuth2 Authorization Code Flow. These are described below.

If you are implementing OAuth2 we strongly recommend using an existing library. The library you choose will depend on your application.

To help you get going straight away we've included an example below using Postman so that you can start experimenting with the Authorization Code Flow.

Request authorization to access Trelica resources

Shows the Trelica authorization page, asking for the user to consent to Trelica sharing information with your web application.

Responses

• HTTP 302

  Redirects the browser to the callback URL you specified, passing the OAuth authorization code and the state (if passed in your request).

  Location: https://client.example.com/your-callback-url?code=<CODE>&state=<STATE>
  

Access Token Request

Exchanges the code received from the authorization request for an access token.

Responses

• HTTP 200

  JSON containing the access token.

  {
      "access_token": "<TOKEN>",
      "expires_in": 3600,
      "token_type": "Bearer",
      "scope": "Users.Read offline_access",
      "refresh_token": "<REFRESH TOKEN>"
  }
  

Refresh tokens

Trelica issues refresh tokens with a 15 day sliding window. That means that if you don't use the token within 15 days it will expire forever. If you do use it within 15 days though, the token will be expired immediately and you will be issued with a new token, again valid for 15 days.

Refresh tokens are granted by posting to the /connect/token endpoint with:

Don't forget that all requests to /connect/token need the Client id and Client Secret passed in the Authorization header using Basic Authentication.

Example

For this example we are going to use the popular Postman application as it handles opening the web browser and granting access.

Create an API App in Trelica

Create a new API app in Trelica and give it a name. Choose Authorization code, make sure the Read users scope is checked, and enter the following Redirect URL:https://oauth.pstmn.io/v1/callback

Copy the Client ID and Client Secret to a text editor like notepad as you'll need them shortly.

Then Save the new API app.

Create a new request in Postman

Load Postman, click New and then choose Request:

Create a new request called Get users (or whatever name you want).

Configure Postman variables

The next thing we'll do is configure two variables. It's best practice in Postman to store credentials and other sensitive data in variables. Near the top you will see the Environment dropdown, and a preview 'eye' icon. Click this, create a new envionment if necessary (or use global variables if you prefer), and then choose Edit to define two variables for clientId and clientSecret.

Paste in the corresponding ID and secret values for the API app that you copied from Trelica earlier.

Close the Manage environments dialog, and go back to your new request.

Configure OAuth2 authentication

Select the Auth tab, and pick OAuth 2.0 from the Type dropdown:

Fill in the Configure New Token section as follows:

Request an access token

When you're done, click Get New Access Token.

Postman will show a Get New Access Token dialog, and open up a web-browser. This will show you a Trelica screen, asking you to authorize your App to access your Trelica account. You may be asked to login first.

Click Authorize and you can go back to Postman, which will have captured the token issued by Trelica:

Click Use Token.

Make the API call

Go back to the request, and enter the API end-point we want to access:

https://app.trelica.com/api/scim/v2/Users

Then click Send:

You'll then see the response come back: