Implementing the 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.

Implementation Steps

Step 1: Redirect Users to Consent Screen

Redirect 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=read_data%20write_data%20manage_integrations&state=random_1234&account-id=example-user-account

Query Parameters:

• client_id: Your application’s client ID (e.g. 6a1c0cac-02c3-4e03-8b93-eb922bf089c0), provided upon app registration. To retrieve it, visit the Developer App Dashboard and click Copy Token in the three-dots menu located in the bottom-left corner.
• redirect_uri: One of the authorized callback URLs (e.g. https://example-app.com/callback).
• response_type: Set to code.
• scope: A space-separated list of permissions your app requires, URL-encoded (e.g., read_data write_data manage_integrations --> read_data%20write_data%20manage_integrations).
• state (optional): A random string to prevent CSRF attacks (e.g. random_1234).
• account_id: 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.

What happens next?

• Users land on the consent screen and are prompted to grant permission to your app.
• After granting consent, they are redirected to your specified redirect_uri. The URL will include a code parameter. Your app should capture this 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 to request access and refresh tokens.

Make 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: Your application’s client ID.
• client_secret: Your application’s client secret.
• code: The authorization code.
• redirect_uri: One of the authorized callback URLs.
• grant_type: 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 successful response will include an access token, its expiration time (in seconds), 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. Note that the access token is valid for 1 hour, after which you’ll need to use the refresh token to obtain a new one.

Step 3: Refresh Expired Access Tokens

The access token expires after 1 hour. To ensure uninterrupted access to the Orcabase API, automate the refresh token flow to generate a new access token without requiring the user to reauthenticate.

Make 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: Your app's client ID, provided upon app registration.
• client_secret: Your app's client secret, provided upon app registration.
• grant_type: refresh_token
• refresh_token: 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 successful response will include 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 is 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: Redirect Users to Integrations Mini-App

After obtaining an access token, redirect users to the Triple Whale Integrations Mini-App sign-in flow. The Integrations Mini-App is a centralized interface where users can manage and connect integrations, enabling your application to access data seamlessly through the Orcabase API.

Integrations Mini-App Sign-in URL

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

Query Parameters:

• account-id: The unique identifier for the authenticated client user (e.g. example-user-account).
• app-id: Your application’s unique identifier, provided during registration as client_id.

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.

What happens next?

• Once connected to one or more providers, users can access data from their selected integrations 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.