Authentication

The API has both the option of using an API Key for authentication, or to use an OAuth2 based flow.

API Key

This is meant for connecting with the API to pull information from your own firm into other (automation) tools.

You need to be a firm admin user to (request to) turn on the Developer API and create an API Key (open integration settings)

The API key needs to be included in the header of every request:

Authorization: Token {apikey}

Example:

Authorization: Token abcd1234

OAuth2 Flow

This is meant for building integrations that can be used by any number of DecisionVault subscribers.

At first the Developer App will only let admin users under your own firm connect - once you have built out your integration, please reach out to DecisionVault support to open it up to all our subscriber firms.

1. Create the Developer App

You need to be a firm admin to take these steps.

Open the integration settings and under Developer Apps click Manage, then choose "Add Developer App"

You'll be asked to provide the following information:

Application Name

URL for a App Favicon (suggested 200x200px PNG)

A list of allowed Redirect URIs (e.g. http://localhost:8000/auth/callback)

After the app is created the next page will show you:

Client ID: xhihLl5uos4OepKndnzhXZ5ynETa0jPwkMKvL2fv
Client Secret: Mjc3MDBmOWEtOWJlNy00MDFjLWFjMGYtM2FhNThhOTBiMjdkOmI3YmUyY

2. Authorization

To start authorization, redirect the user to the following URL you can build up with the above information:

https://app.decisionvault.com/oauth/authorize?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>&state=<random string>

Your user will land on a screen where they can authorize your application to connect.

If successful, the user will get redirected to the Redirect URI, and there will be a ?code=ABCDEFG attribute attached at the end of the URL. And the system will send back the state parameter so you can compare this against the value passed in.

3. Get the access & refresh tokens

Use the code from the URL and other parameters to make a POST request from your backend to request tokens:

POST request to https://app.decisionvault.com/oauth/token
Form URL-Encoded

grant_type=authorization_code
redirect_uri=<your redirect_uri>
code=<code>
client_id=<client_id>
client_secret=<client_secret>

The OAuth token provider will reply with:

{
  "access_token": "jooqrnOrNa0BrNWlg68u9sl6SkdFZg",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "HNvDQjjsnvDySaK0miwG4lttJEl9yD"
}

4. Access the API

The bearer access token needs to be included in the header of every request to access API Endpoints:

Authorization: Bearer {access_token}

Example:

Authorization: Bearer jooqrnOrNa0BrNWlg68u9sl6SkdFZg

Base Url

The Base Url for the production environment is https://api.decisionvault.com/v1

The Base Url for the staging environment is https://staging-api.decisionvault.com/v1

5. Using the refresh token

To use the refresh token to get a new access token, make the following request to the token endpoint:

POST request to https://app.decisionvault.com/oauth/token
Form URL-Encoded

grant_type=refresh_token
refresh_token=<refresh_token>
client_id=<client_id>
client_secret=<client_secret>

You'll get a new access token & refresh token:

{
  "access_token": "xdAUl3FElMqSS1ZlzWyyzXYRyOSNBL",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "lyuUpX6rDO2FMW80bZsRuAySBy1zBh"
}

API Key#

OAuth2 Flow#

1. Create the Developer App#

2. Authorization#

3. Get the access & refresh tokens#

4. Access the API#

Base Url#

5. Using the refresh token#