Skip to content

Generating tokens via oAuth

Overview

This fact sheet details how third-party integrators can allow their users to generate a VaultRE API token from within their system, without storing the user's VaultRE username/password. This is achieved with an OAuth2 style flow.

Getting started

If you wish to use an OAuth2 flow to generate API tokens, contact api@vaultre.com.au and:

  • Request your client ID. This is a different value to your API key.

  • Advise us of your redirect URI(s). This is a list of URIs that we will accept for redirecting your users back to your application - redirect URIs are explicit as per Redirect URI Parameters below.

    Note that you can have multiple redirect URIs to facilitate your development, staging and production environments, as well as any white-labelling requirements you may have.

Redirect URI Parameters

We do not support any custom parameters in OAuth call; you can place variables within the redirect URI but they have to be explicitly defined within the list of URIs.

For example, if you provide the following list of redirect URIs:"demo.com/some-stuff/auth,demo.com/some-stuff/auth?exampleparameter=value1, demo.com/some-stuff/auth?exampleparameter=value2, demo.com/some-stuff/auth?exampleparameter=value3"

This will be the result:

https://login.vaultre.com.au/cgi-bin/clientvault/oauth-authorize.cgi?client_id=<client_id>&response_type=code&redirect_uri=demo.com%2Fsome-stuff%2Fauth
Works
https://login.vaultre.com.au/cgi-bin/clientvault/oauth-authorize.cgi?client_id=<client_id>&response_type=code&redirect_uri=demo.com%2Fsome-stuff%2Fauth%3Fexampleparameter%3Dvalue1
Works
https://login.vaultre.com.au/cgi-bin/clientvault/oauth-authorize.cgi?client_id=<client_id>&response_type=code&redirect_uri=demo.com%2Fsome-stuff%2Fauth%3Fexampleparameter%3Dvalue2
Works
https://login.vaultre.com.au/cgi-bin/clientvault/oauth-authorize.cgi?client_id=<client_id>&response_type=code&redirect_uri=demo.com%2Fsome-stuff%2Fauth%3Fexampleparameter%3Dvalue3
Works
https://login.vaultre.com.au/cgi-bin/clientvault/oauth-authorize.cgi?client_id=<client_id>&response_type=code&redirect_uri=demo.com%2Fsome-stuff%2Fauth%3Fexampleparameter%3Dvalue4
Fails
https://login.vaultre.com.au/cgi-bin/clientvault/oauth-authorize.cgi?client_id=<client_id>&response_type=code&redirect_uri=demo.com%2Fsome-stuff%2Fauth%3Fdifferentparameter%3Dvalue1
Fails

Decide what type of access you need

Two types of tokens can be generated.

  1. Tokens that can access data at an "office/account" level (third party tokens)
  2. Tokens that can access data at a "user/person" level (user tokens)

If your integration needs account access, only a system admin user can complete the authentication flow.

Technical guide

To initiate the OAuth flow, include a link to the following URL from within your application:

Third Party Tokens

https://login.vaultre.com.au/cgi-bin/clientvault/oauth-authorize.cgi?client_id=<client_id>&redirect_uri=<redirect_uri>&response_type=code

User Tokens

https://login.vaultre.com.au/cgi-bin/clientvault/oauth-authorize-user.cgi?client_id=<client_id>&redirect_uri=<redirect_uri>&response_type=code

If the user is not currently logged in to VaultRE, they will be required to do so.

Once they are logged in, they will be redirected to a screen similar to the below:

VaultRE Office Integrations Menu

VaultRE Office Integrations Menu

If the user clicks "Cancel", they will be redirected back to your redirect_uri with the query parameter ?reason=User%20denied%20request.

If the user clicks "Confirm", they will be redirected back to your redirect_uri with the query parameters ?reason=success&code=<code>.

Please note that you can optionally include a "state" variable in the above URLs, to allow you to verify that a request originated in your system. This variable will be retained through the oAuth flow and will be returned to your callback URL.

Once you obtain the <code> value, you'll need to exchange the code for an Access Token.

Please note that this token exchange MUST be done using server-side code, as our CORS policy will block attempts to do this with client-side code (i.e. in the browser).

An example cURL request to do the exchange:

curl -X POST ‘https://login.vaultre.com.au/cgi-bin/clientvault/integrations/oauthexchange.cgi’ -d 'client_id=<client_id>&code=<code>’

Note that the <code> value is only valid for 60 seconds.

A successful response from this exchange will include a JSON payload like the below:

{"token": "<token>", "message": "Token generated successfully"}

You can now use this Access Token in conjunction with your API key to access the VaultRE API.

Please note that the user can revoke this token at any time from within their VaultRE account.