OAuth

VENTURE.co is able to act as an OAuth 2.0 provider. Implementing this flow is the only supported way to use VENTURE.co’s platform to manage your user accounts. We strive to have a spec compliant OAauth 2.0 implementation. If you find parts of the flow do not adhere to this spec please contact our lead developer, charles@venture.co.

Overview

Below we detail the following steps that must be completed to retrieve an authentiction token that can be used to authorize all subsequent API requests.

Redirect the user to VENTURE.co sign-in process.
Upon successful verification redirect back to integrating platform with temporary authentication code.
Turn authentication code into an authentication token.

The first step is to ensure the user has signed in to the VENTURE.co platform and approved your application to access data on their behalf. This is accomplished by redirecting the user to our sign-in flow with a specific set of parameters to identify your client. The following parameters must be provided in the redirect URL:

client_id A unique identifier provided by VENTURE.co when your OAuth application is created.
redirect_uri An absolute URL that the user will be redirected to when successfully verified your app’s permissions.
state A nonce generated by your application to prevent CSRF.
scope A string representing the permissions requested by your app, can be either basic or full. Basic is very limited and Full allows complete read+write access

Example:

With a client ID of client1234, state of state9876, and a redirect URI of https://www.example.com the following URL should be redirected to:

https://accounts-staging.venture.co/auth/login/oauth/authorize?client_id=client1234&state=state9876&redirect_uri=https%3A%2F%2Fwww.example.com&scope=full

To hit the production endpoint simply remove -staging from the above URL.

You MUST NOT send your client_secret in the redirect request. This is sensitive information that MUST NOT be exposed except for direct server-to-server communications.

Back to integrating platform

If the user successfully logged in and confirmed your app’s permissions they will be redirected back to your application using the redirect_uri paramter provided in step 1, ‘Redirect to sign-in’. Two query parameters will be attached to this URL:

code A temporary authorization code that can be used to retrieve an authentication token
state The same nonce that was set as the state in step 1.

It is very important that you verify the state in this step is valid for your platform. Without appropriate validation of the state CSRF prevention cannot be guaranteed. At this point you’re ready to turn this temporary code into a token that can be used in subsequent requests to the API.

Turn code into a token

Once you’re ready to turn your temporary authorization code into a permanent token you do so by making a POST request similar to the following:

POST /v2/core/oauth/token?grant_type=authorization_code

{
  "client_id": "client1234",
  "client_secret": "client1234secret",
  "code": "code1234",
  "state": "state9876"
}

The response does not follow the AMS convention and will be returned similar to below:

{

  "token_type": "bearer",
  "access_token": "#####",
  "refresh_token": "#####"
}

If everything was returned successfully you can now use the access_token to authenticate future requests.