User Connection Flow

The Orcabase User Connection Flow gives your registered users a seamless connection experience, consisting of a simple Triple Whale consent screen with no need for an additional external signup step. The Orcabase API uses OAuth 2.0, a secure and widely used protocol, to manage authentication and authorization behind the scenes. This process protects user data and enables your application to securely access the API.

Step 1: Direct Users to the Consent Screen

Send users to the Triple Whale OAuth consent screen to grant the necessary permissions.

Example Consent URL

https://api.triplewhale.com/api/v2/orcabase/dev/auth?client_id=6a1c0cac-02c3-4e03-8b93-eb922bf089c0&redirect_uri=https://example-app.com/callback&response_type=code&scope=offline_access%20offline&state=random_1234&account_id=example-user-account

Query Parameters:

• client_id (required): Your application’s client ID (e.g. 6a1c0cac-02c3-4e03-8b93-eb922bf089c0), provided upon app registration. Retrieve it from App Settings.
• redirect_uri (required): One of the authorized callback URLs you gave upon app registration (e.g. https://example-app.com/callback).
• response_type (required): Set to code.
• scope (required): Required scopes are offline_access and offline (to enable the refresh token process), formatted as a URL-encoded space-separated list:offline_access%20offline.
• state (required): A random string to prevent CSRF attacks (e.g. random_1234).
• account_id (required): The unique Account ID for each registered user account you have added to Orcabase (e.g. example-user-account). Retrieve it from the Developer App Dashboard.

What happens next?

• Users are redirected to the specified redirect_uri with a code parameter included in the URL. Capture this authorization code for the next step.

Example Redirect URI with `code` Parameter

https://yourapp.com/callback?code=<AUTHORIZATION_CODE>&state=<STATE>

• Once a user has granted consent, their Auth Status will change to Online in the Developer App Dashboard.

Step 2: Exchange Authorization Code for Tokens

Use the authorization code captured in the previous step to request access tokens and refresh tokens by sending a POST request to the token endpoint:

Token Endpoint

POST https://api.triplewhale.com/api/v2/auth/oauth2/token

Headers:

• Content-Type: application/x-www-form-urlencoded

Request Body:

• client_id (required): Your application’s client ID.
• client_secret (required): Your application’s client secret.
• code (required): The authorization code.
• redirect_uri (required): One of the authorized callback URLs.
• grant_type (required): authorization_code.

Example Request

POST /api/v2/auth/oauth2/token HTTP/1.1
Host: api.triplewhale.com
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code=AUTH_CODE
&redirect_uri=https://yourapp.com/callback
&grant_type=authorization_code

Response:

The response will include an access token, its expiration time, and a refresh token.

Example Response

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

If the token exchange fails, log the error for debugging and display an appropriate message to the user, prompting them to retry the authorization process.

Once you have an access token, you can use it to authenticate API requests.

Step 3: Refresh Expired Access Tokens

Access tokens expire after 1 hour. Automate the refresh token process to generate new access tokens without requiring user reauthentication.

Send a POST request to the token endpoint:

Token Endpoint

POST https://api.triplewhale.com/api/v2/auth/oauth2/token

Headers:

• Content-Type: application/x-www-form-urlencoded

Request Body:

• client_id (required): Your app's client ID, provided upon app registration.
• client_secret (required): Your app's client secret, provided upon app registration.
• grant_type (required): refresh_token
• refresh_token (required): The refresh token you received during the initial token exchange.

Example Request

POST /api/v2/auth/oauth2/token HTTP/1.1
Host: api.triplewhale.com
Content-Type: application/x-www-form-urlencoded

client_id=your-client-id
&client_secret=your-client-secret
&grant_type=refresh_token
&refresh_token=your-refresh-token

Response:

The response includes a new access token, its expiration time (in seconds), and a new refresh token (valid for 30 days). Save the new refresh token; the previous refresh token will now be expired and cannot be used again.

Example Response

{
  "access_token": "new-access-token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "new-refresh-token"
}

If the refresh token is invalid or expired, prompt the user to reauthenticate and obtain a new authorization code.

Step 4: Retrieve User Sign-In Token and Redirect to Integrations Mini-App

To enable your users to manage and connect their integrations, retrieve their secure sign-in token and redirect them to the Integrations Mini-App.

Retrieve the Sign-In Token

Send a POST request to the /sign-in-account endpoint to retrieve a secure user sign-in token.

Note: Include this sign-in token every time you redirect users to the Integrations Mini-App (not just the first time they authenticate).

Redirect to Integrations Mini-App

After retrieving the sign-in token, redirect the user to the Integrations Mini-App:

Integrations Mini-App Sign-in URL

https://orcabase.app.triplewhale.com/integrations?account-id=example-user-account&app-id=6a1c0cac-02c3-4e03-8b93-eb922bf089c0&token=<TOKEN>

Query Parameters:

• account-id (required): The unique Account ID for each registered user account you have added to Orcabase (e.g. example-user-account). To retrieve it, visit the Developer App Dashboard and copy the value from the Account column.
• app-id (required): Your app’s unique client ID token, provided during developer app registration as client_id. To retrieve it, visit Developer App > App Settings.
• token (required): The secure user account sign-in token retrieved using the /sign-in-account endpoint.

What happens next?

• In the Integrations Mini-App, users will see the list of providers that you selected upon app registration.
• Users can click Connect to grant access to one or more of these providers, so that they can request data from those sources via the Orcabase API endpoints.
• Once connected to one or more providers, users can query data via Orcabase API endpoints.

Best Practices

• Request Minimal Scopes: Ask for only the permissions your app needs to build trust and follow the principle of least privilege.
• Use State for Security: Include a unique state parameter in the consent URL and verify it on return to prevent CSRF attacks.
• Secure Token Handling: Keep tokens and sensitive credentials (client_secret) on the server side only. Avoid exposing them in client-side code or logs to reduce the risk of unauthorized access.