Authorization code flow


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.

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.


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.

prompt string

login | consent

  • this will force the user to either login (even if they're currently logged in), or re-consent (even if they've already granted consent)
state string

An opaque value used by your web application to maintain state between the request and callback. This value is included by Trelica when redirecting the browser back to your web application. This parameter also prevents cross-site request forgery.

redirect_uri * string

The URL to redirect to. This must match a URL defined in the Trelica app.

client_id * string

The Trelica app Client ID

scope string

The OAuth scopes for the data you want to access. The string is case-sensitive. Multiple scopes must be separated by a space character. If no value is passed then all scopes defined for the app will be requested.

response_type string



  • HTTP 302

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


Access Token Request


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

Authorization * string

As per the HTTP Basic Authentication Scheme, i.e. Client ID and Client Secret concatenated with a colon, Base64 encoded, and prepended with the string "Basic ".

refresh_token string

The previously issued refresh token. Required if the grant_type is refresh_token

client_id string

The Trelica app Client ID. Required if the grant_type is authorization_code

redirect_uri string

Required if the redirect_uri parameter was included in the authorization request. The value must be identical. Required if the grant_type is authorization_code

code string

The authorization code received from Trelica. Required if the grant_type is authorization_code

grant_type * string

authorization_code or refresh_token


  • 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>"

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.


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:

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)
Auth URL
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:

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.

Was this article helpful?

0 out of 0 found this helpful



Please sign in to leave a comment.