Building an OAuth Application
If you're building an application for others to use with their Increase accounts, our API supports OAuth 2.0. The first step is to create an OAuth application in the Dashboard. You will set a name and a redirect_url and receive a client_id and a client_secret.
The authorization flow
At a high level, onboarding users to your OAuth application looks like this:
- The user begins on your site, where they're redirected to Increase's site and prompted to grant you access to their Increase data.
- Upon granting access, the user is redirected back to your site with a short-lived OAuth code.
- You use our API to exchange this code for a long-lived access token, which you use to authenticate to the API on subsequent requests on behalf of the user.
Request access from your user
To request access from your user, build an OAuth authorization URL using the client_id and client_secret you received when creating your application and direct your user to it. You must also specify a scope of either read_only or read_write which is the permissions the user will be prompted to grant your application. You may also optionally include a state value which will be included when the user is redirected back to your site after approving access and can be used for tracking your user’s identity and preventing Cross-Site Request Forgeries (CSRFs). This IETF draft article provides a good overview of the latter.
Your URL should be of the format:
Claim an Access Token
When a user grants you access they'll be redirected to {redirect_url}?code={code}&state={state}. You should then use our API to exchange this code for an access token. The code expires after 60 seconds. You’ll also need to provide your application’s client_id and client_secret, as well as a parameter grant_type with the constant value of authorization_code.
This will return an access token that looks like this:
You’ll need to store this access token in your application.
Access the API on behalf of your user
Use the returned access_token in place of your own API key to access the user's account, and then make API requests as you normally would. If your application’s scope is read_only, only GET requests will be allowed.
Create a sandbox token
If you need to access your user’s sandbox environment, you can create a separate sandbox access token to do so. You use your own sandbox token when making this request, and provide the access_token you received at the end of the authorization flow for the production_token parameter. You’ll also need to include the parameter grant_type with the constant value of production_token.
Webhooks
If you have an Event Subscription configured, you’ll receive webhooks for activity on your own platform’s account as well as for activity on your connected accounts. You can distinguish the latter via the presence of the Increase-Group-Id header on the webhook request, which will be set to the ID of the Group the activity occurred on. Note that your Event Subscription should belong to your platform’s account, not your connected user’s account (in other words, you should create it with your normal API key, not an OAuth access token).
Managing connected accounts
You can list all of the groups that have connected your application using the OAuth Connections API. Note that this API, like the Event Subscriptions API, should be accessed with your platform’s API key and not with a user’s OAuth access token.
You can retrieve information for an individual connected account by calling the Retrieve Group API with a user’s OAuth access token.
Users can deauthorize your application at any time in their Dashboard. When this happens, we’ll send your application an oauth_connection.deactivated webhook. Subsequent API calls with that user’s access token will return an invalid_api_key_error response with HTTP status code 401.