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. 1.
    User clicks 'Connect to Trelica' button in your web application.
  2. 2.
    Your web application redirects the user's browser to the Trelica /connect/authorize URL.
  3. 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. 4.
    Trelica redirects the user's browser back to a page in your web application, appending an authorization code (if access was granted)
  5. 5.
    Your web application swaps this authorization code for a Trelica access token.
  6. 6.
    Your web application then communicates to the user that the connection was successful.
Step 3 may be transparent to the user if the user is already logged in to Trelica in the current browser session, and if they have already granted access to your application.

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.
get
https://app.trelica.com
/connect/authorize
Request authorization to access Trelica resources
post
https://app.trelica.com
/connect/token
Access Token Request
When requesting an Access Token, you must pass the Client ID and Client Secret in the Authorization header using the standard HTTP Basic Authentication Scheme.
Access tokens expire by default after 60 minutes. If you want to keep accessing data (e.g. from a background task in your application) then you should also request the offline_access scope. This will issue a refresh token which you can then use to get a new access 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:
Key
Value
grant_type
refresh_token
refresh_token
The refresh token issued when you obtained the access token (using the offline_access scope)
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:
Field
Value
Token Name
token
Grant Type
Authorization Code
Authorize using browser
(checked)
Access Token URL
Client ID
{{clientId}}
Client Secret
{{clientSecret}}
Scope
Users.Read
State
(can be left empty)
Client Authentication
Send as Basic Auth header
Note how Postman uses double braces to insert variables into fields.

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:
By default your access token will expire after an hour, and you'll then need to reauthenticate (in the Authorization tab on the left, where you configured the token request).
If you're writing an application that needs to access data for a longer period of time, then providing you requested the offline_access scope, you will have been issued a refresh token to use to obtain a new access token.
Copy link
Outline
Overview
Authentication
get
Request authorization to access Trelica resources
post
Access Token Request
Refresh tokens
Example
Create an API App in Trelica
Create a new request in Postman
Configure Postman variables
Configure OAuth2 authentication
Request an access token
Make the API call