AptlyStar

Create OAuth Apps For Integrations

What to create for each OAuth integration, which keys to collect, and how to get them

This guide is for workspace admins and operators who need to create OAuth apps for Aptlystar integrations. It focuses on the practical setup work: what app to create in each provider, what values to copy out of that provider, and which Aptlystar environment variables those values belong in.

This page covers user-consent OAuth integrations. Google service accounts use a different flow. See Google Service Accounts.

What You Need From Each Provider

For almost every OAuth integration, you need to collect these values from the provider portal:

  • client id
  • client secret
  • registered redirect URI or callback URL
  • approved scopes or permissions
  • sometimes an app review or publish step before the integration works for non-admin users

The main exception in the current codebase is trello, which uses an API key instead of a client ID and client secret pair.

How Redirect URIs Work In Aptlystar

Most integrations use this redirect URI pattern:

${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/{provider-id}

Special cases:

  • shopify uses /api/auth/oauth2/callback/shopify
  • trello uses /api/auth/trello/callback

Always register the public browser-facing URL, not INTERNAL_API_BASE_URL or any internal cluster URL.

Keep these two app env vars aligned for each environment:

BETTER_AUTH_URL=<public app origin>
NEXT_PUBLIC_APP_URL=<public app origin>

Environment Examples

Use your real public domain for each environment:

EnvironmentExample public originRequired app env
Localhttp://localhost:3000BETTER_AUTH_URL, NEXT_PUBLIC_APP_URL
Testhttps://staging.example.comBETTER_AUTH_URL, NEXT_PUBLIC_APP_URL
Productionhttps://app.example.comBETTER_AUTH_URL, NEXT_PUBLIC_APP_URL

If a provider lets you register multiple redirect URIs in one OAuth app, you can usually use one provider app for local, test, and production. If a provider only allows one redirect URI, create one provider app per environment.

The Basic Workflow

Pick the provider you want to enable in Aptlystar.

Create an OAuth app in that provider's developer portal.

Add the Aptlystar redirect URI for local, test, and production.

Copy the client ID, client secret, or API key into the matching Aptlystar env vars.

Restart the app, then test the connection in Settings → Integrations.

Provider Groups At A Glance

Some Aptlystar integrations share one provider app:

  • Google: Gmail, Calendar, Drive, Docs, Sheets, Contacts, Forms, Ads, BigQuery, Vault, Groups, Meet, Tasks, Vertex AI
  • Microsoft: Teams, Excel, Dataverse, Planner, Outlook, OneDrive, SharePoint, Microsoft Ads
  • Atlassian: Confluence and Jira are separate registrations in the current codebase

The rest are usually one provider app per integration.

Shared Provider Apps

Google Cloud

Covers

  • Gmail
  • Google Calendar
  • Google Drive
  • Google Docs
  • Google Sheets
  • Google Contacts
  • Google Forms
  • Google Ads
  • BigQuery
  • Google Vault
  • Google Groups
  • Google Meet
  • Google Tasks
  • Vertex AI

Collect from Google

  • client ID
  • client secret

Set in Aptlystar

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

Redirect URIs to register

  • /api/auth/oauth2/callback/google-email
  • /api/auth/oauth2/callback/google-calendar
  • /api/auth/oauth2/callback/google-drive
  • /api/auth/oauth2/callback/google-docs
  • /api/auth/oauth2/callback/google-sheets
  • /api/auth/oauth2/callback/google-contacts
  • /api/auth/oauth2/callback/google-forms
  • /api/auth/oauth2/callback/google-ads
  • /api/auth/oauth2/callback/google-bigquery
  • /api/auth/oauth2/callback/google-vault
  • /api/auth/oauth2/callback/google-groups
  • /api/auth/oauth2/callback/google-meet
  • /api/auth/oauth2/callback/google-tasks
  • /api/auth/oauth2/callback/vertex-ai

Steps

  1. Open Google Cloud Console and create or pick a project.
  2. Open APIs & Services and configure the OAuth consent screen.
  3. Enable the APIs you plan to use.
  4. Open Credentials and create an OAuth client ID for a web application.
  5. Add the Aptlystar redirect URIs above for local, test, and production.
  6. Copy the client ID and client secret into GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.

Notes

  • Aptlystar requests offline access and stores refresh tokens.
  • Review the provider scopes in apps/aptlystar/lib/oauth/oauth.ts before finalizing the consent screen.

Microsoft Entra ID

Covers

  • Microsoft Ads
  • Microsoft Teams
  • Microsoft Excel
  • Microsoft Dataverse
  • Microsoft Planner
  • Outlook
  • OneDrive
  • SharePoint

Collect from Microsoft

  • application/client ID
  • client secret

Set in Aptlystar

MICROSOFT_CLIENT_ID=
MICROSOFT_CLIENT_SECRET=

Redirect URIs to register

  • /api/auth/oauth2/callback/microsoft-ad
  • /api/auth/oauth2/callback/microsoft-teams
  • /api/auth/oauth2/callback/microsoft-excel
  • /api/auth/oauth2/callback/microsoft-dataverse
  • /api/auth/oauth2/callback/microsoft-planner
  • /api/auth/oauth2/callback/outlook
  • /api/auth/oauth2/callback/onedrive
  • /api/auth/oauth2/callback/sharepoint

Steps

  1. Open Microsoft Entra ID and go to App registrations.
  2. Create a New registration.
  3. Under Supported account types, choose Accounts in any organizational directory and personal Microsoft accounts if you want the app registration to allow both work/school accounts and personal Microsoft accounts.
  4. Add a Web redirect URI for each Aptlystar callback you need.
  5. Open Certificates & secrets and create a new client secret.
  6. Open API permissions and add the Microsoft Graph or Dataverse permissions needed by Aptlystar.
  7. Copy the Application (client) ID and the generated secret into MICROSOFT_CLIENT_ID and MICROSOFT_CLIENT_SECRET.

Notes

  • These integrations use PKCE and offline_access.
  • Review requested permissions in apps/aptlystar/lib/oauth/oauth.ts.
  • Even with a multi-tenant + personal app registration, not every Aptlystar Microsoft integration is practical for personal Microsoft accounts.
  • outlook, onedrive, and microsoft-excel are the most likely to work with personal accounts.
  • microsoft-ad, microsoft-teams, sharepoint, microsoft-planner, and microsoft-dataverse are typically work or school account integrations because they depend on org or tenant-level Microsoft Graph and Dataverse permissions.

Atlassian

Atlassian uses separate app registrations in the current Aptlystar env model.

Confluence

Collect

  • client ID
  • client secret

Set in Aptlystar

CONFLUENCE_CLIENT_ID=
CONFLUENCE_CLIENT_SECRET=

Redirect URI

${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/confluence

Steps

  1. Open Atlassian's developer console.
  2. Create an OAuth 2.0 app for Confluence.
  3. Add the Aptlystar redirect URIs for local, test, and production.
  4. Configure the scopes Aptlystar needs.
  5. Copy the client ID and client secret into CONFLUENCE_CLIENT_ID and CONFLUENCE_CLIENT_SECRET.

Jira

Collect

  • client ID
  • client secret

Set in Aptlystar

JIRA_CLIENT_ID=
JIRA_CLIENT_SECRET=

Redirect URI

${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/jira

Steps

  1. Open Atlassian's developer console.
  2. Create a separate OAuth 2.0 app for Jira.
  3. Add the Aptlystar redirect URIs.
  4. Configure Jira scopes, including the extra Jira Service Management scopes if you use JSM features.
  5. Copy the client ID and client secret into JIRA_CLIENT_ID and JIRA_CLIENT_SECRET.

One Provider App Per Integration

The sections below tell you what to create and what to collect for the remaining OAuth integrations.

Slack

  • Create: Slack app
  • Collect: client ID, client secret
  • Set in Aptlystar: SLACK_CLIENT_ID, SLACK_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/slack
  • Steps: Open Slack API apps, create a new app, add redirect URIs under OAuth & Permissions, add the scopes Aptlystar needs, then copy the client ID and client secret from the app settings.

Notion

  • Create: Notion public integration
  • Collect: client ID, client secret
  • Set in Aptlystar: NOTION_CLIENT_ID, NOTION_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/notion
  • Steps: Open the Notion integrations portal, create a new public integration, add the Aptlystar redirect URIs in the OAuth settings, then copy the client ID and client secret.

Monday.com

  • Create: Monday app
  • Collect: client ID, client secret
  • Set in Aptlystar: MONDAY_CLIENT_ID, MONDAY_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/monday
  • Steps: Open the Monday developer center, create an app, enable OAuth, add Aptlystar redirect URIs, then copy the client ID and client secret.

Airtable

  • Create: Airtable OAuth integration
  • Collect: client ID, client secret
  • Set in Aptlystar: AIRTABLE_CLIENT_ID, AIRTABLE_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/airtable
  • Steps: Open Airtable's developer area, create a new OAuth integration, register the Aptlystar redirect URIs, configure the scopes, then copy the client ID and client secret.

HubSpot

  • Create: HubSpot public app
  • Collect: client ID, client secret
  • Set in Aptlystar: HUBSPOT_CLIENT_ID, HUBSPOT_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/hubspot
  • Steps: Open your HubSpot developer account, create an app, open the Auth section, add the Aptlystar redirect URIs, set the required scopes, then copy the client ID and client secret.

Salesforce

  • Create: Salesforce connected app
  • Collect: consumer key, consumer secret
  • Set in Aptlystar: SALESFORCE_CLIENT_ID, SALESFORCE_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/salesforce
  • Steps: Open Salesforce App Manager, create a New Connected App, enable OAuth settings, add the Aptlystar callback URI, choose the required scopes, then copy the consumer key and consumer secret into the Aptlystar env vars.

Linear

  • Create: Linear OAuth app
  • Collect: client ID, client secret
  • Set in Aptlystar: LINEAR_CLIENT_ID, LINEAR_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/linear
  • Steps: Open Linear developer settings, create an OAuth app, add the Aptlystar redirect URIs, then copy the client ID and client secret.

Box

  • Create: Box custom app with OAuth 2.0 user authentication
  • Collect: client ID, client secret
  • Set in Aptlystar: BOX_CLIENT_ID, BOX_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/box
  • Steps: Open the Box developer console, create a custom app that uses OAuth 2.0, add the Aptlystar redirect URIs, enable the scopes you need, then copy the client ID and client secret.

Dropbox

  • Create: Dropbox app
  • Collect: app key, app secret
  • Set in Aptlystar: DROPBOX_CLIENT_ID, DROPBOX_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/dropbox
  • Steps: Open the Dropbox App Console, create an app, add the Aptlystar redirect URIs, configure the required permissions, then copy the app key and app secret.

Asana

  • Create: Asana OAuth app
  • Collect: client ID, client secret
  • Set in Aptlystar: ASANA_CLIENT_ID, ASANA_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/asana
  • Steps: Open the Asana developer console, create a new app, add the Aptlystar callback URI, then copy the client ID and client secret.

Pipedrive

  • Create: Pipedrive OAuth app
  • Collect: client ID, client secret
  • Set in Aptlystar: PIPEDRIVE_CLIENT_ID, PIPEDRIVE_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/pipedrive
  • Steps: Open Pipedrive's developer portal, create an OAuth app, add the Aptlystar redirect URIs, then copy the client ID and client secret.

Wealthbox

  • Create: Wealthbox OAuth application
  • Collect: client ID, client secret
  • Set in Aptlystar: WEALTHBOX_CLIENT_ID, WEALTHBOX_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/wealthbox
  • Steps: Open the Wealthbox developer settings, create an OAuth application, register the Aptlystar callback URI, then copy the client ID and client secret.

LinkedIn

  • Create: LinkedIn app
  • Collect: client ID, client secret
  • Set in Aptlystar: LINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/linkedin
  • Steps: Open the LinkedIn developer portal, create an app, open the auth products or OAuth settings, add the Aptlystar redirect URIs, then copy the client ID and client secret.

Reddit

  • Create: Reddit web app
  • Collect: client ID, client secret
  • Set in Aptlystar: REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/reddit
  • Steps: Open Reddit app preferences, create a new web app, add the Aptlystar callback URI, then copy the app ID as the client ID and the secret as the client secret.

Webflow

  • Create: Webflow app
  • Collect: client ID, client secret
  • Set in Aptlystar: WEBFLOW_CLIENT_ID, WEBFLOW_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/webflow
  • Steps: Open the Webflow developer portal, create an app, configure OAuth redirect URIs, then copy the client ID and client secret.

X

  • Create: X app with OAuth 2.0 user authentication
  • Collect: client ID, client secret
  • Set in Aptlystar: X_CLIENT_ID, X_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/x
  • Steps: Open the X developer portal, create a project and app if needed, enable OAuth 2.0 user authentication, add the Aptlystar callback URI, then copy the client ID and client secret.

Zoom

  • Create: Zoom OAuth app
  • Collect: client ID, client secret
  • Set in Aptlystar: ZOOM_CLIENT_ID, ZOOM_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/zoom
  • Steps: Open Zoom Marketplace, build an OAuth app, add Aptlystar redirect URIs, configure scopes, then copy the client ID and client secret.

Spotify

  • Create: Spotify app
  • Collect: client ID, client secret
  • Set in Aptlystar: SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/spotify
  • Steps: Open the Spotify developer dashboard, create an app, add the Aptlystar redirect URIs in the app settings, then copy the client ID and client secret.

WordPress.com

  • Create: WordPress.com OAuth app
  • Collect: client ID, client secret
  • Set in Aptlystar: WORDPRESS_CLIENT_ID, WORDPRESS_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/wordpress
  • Steps: Open the WordPress.com developer app page, create an OAuth app, add the Aptlystar redirect URIs, then copy the client ID and client secret.

DocuSign

  • Create: DocuSign app or integration key setup
  • Collect: client ID, client secret
  • Set in Aptlystar: DOCUSIGN_CLIENT_ID, DOCUSIGN_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/docusign
  • Steps: Open DocuSign Apps and Keys, create a new app or integration key, enable OAuth, add the Aptlystar redirect URIs, then copy the client ID and client secret.

Attio

  • Create: Attio OAuth app
  • Collect: client ID, client secret
  • Set in Aptlystar: ATTIO_CLIENT_ID, ATTIO_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/attio
  • Steps: Open Attio's developer settings, create an OAuth app, add the Aptlystar callback URI, then copy the client ID and client secret.

Cal.com

  • Create: Cal.com OAuth app
  • Collect: client ID
  • Set in Aptlystar: CALCOM_CLIENT_ID
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/calcom
  • Steps: Open Cal.com's developer settings, create an OAuth app, add the Aptlystar callback URI, then copy the client ID. The current Aptlystar env schema only exposes CALCOM_CLIENT_ID.

Shopify

  • Create: Shopify app
  • Collect: client ID, client secret
  • Set in Aptlystar: SHOPIFY_CLIENT_ID, SHOPIFY_CLIENT_SECRET
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/oauth2/callback/shopify
  • Steps: Open the Shopify Partners dashboard, create an app, configure the App URL and allowed redirection URL(s), add the Aptlystar callback URI, then copy the client ID and client secret.
  • Important: Users also need to provide their store-name.myshopify.com domain when connecting Shopify inside Aptlystar.

Trello

  • Create: Trello API key setup
  • Collect: API key
  • Set in Aptlystar: TRELLO_API_KEY
  • Redirect URI: ${NEXT_PUBLIC_APP_URL}/api/auth/trello/callback
  • Steps: Open Trello developer settings, generate an API key, register the Aptlystar return URL if Trello asks for it, then copy the API key into TRELLO_API_KEY.
  • Important: Trello does not use a client secret in the current Aptlystar flow.

Quick Reference Matrix

IntegrationWhat you need to collectAptlystar env vars
Google familyclient ID, client secretGOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
Microsoft familyclient ID, client secretMICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET
Confluenceclient ID, client secretCONFLUENCE_CLIENT_ID, CONFLUENCE_CLIENT_SECRET
Jiraclient ID, client secretJIRA_CLIENT_ID, JIRA_CLIENT_SECRET
Slackclient ID, client secretSLACK_CLIENT_ID, SLACK_CLIENT_SECRET
Notionclient ID, client secretNOTION_CLIENT_ID, NOTION_CLIENT_SECRET
Monday.comclient ID, client secretMONDAY_CLIENT_ID, MONDAY_CLIENT_SECRET
Airtableclient ID, client secretAIRTABLE_CLIENT_ID, AIRTABLE_CLIENT_SECRET
HubSpotclient ID, client secretHUBSPOT_CLIENT_ID, HUBSPOT_CLIENT_SECRET
Salesforceconsumer key, consumer secretSALESFORCE_CLIENT_ID, SALESFORCE_CLIENT_SECRET
Linearclient ID, client secretLINEAR_CLIENT_ID, LINEAR_CLIENT_SECRET
Boxclient ID, client secretBOX_CLIENT_ID, BOX_CLIENT_SECRET
Dropboxapp key, app secretDROPBOX_CLIENT_ID, DROPBOX_CLIENT_SECRET
Asanaclient ID, client secretASANA_CLIENT_ID, ASANA_CLIENT_SECRET
Pipedriveclient ID, client secretPIPEDRIVE_CLIENT_ID, PIPEDRIVE_CLIENT_SECRET
Wealthboxclient ID, client secretWEALTHBOX_CLIENT_ID, WEALTHBOX_CLIENT_SECRET
LinkedInclient ID, client secretLINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET
Redditclient ID, client secretREDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET
Webflowclient ID, client secretWEBFLOW_CLIENT_ID, WEBFLOW_CLIENT_SECRET
Xclient ID, client secretX_CLIENT_ID, X_CLIENT_SECRET
Zoomclient ID, client secretZOOM_CLIENT_ID, ZOOM_CLIENT_SECRET
Spotifyclient ID, client secretSPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET
WordPress.comclient ID, client secretWORDPRESS_CLIENT_ID, WORDPRESS_CLIENT_SECRET
DocuSignclient ID, client secretDOCUSIGN_CLIENT_ID, DOCUSIGN_CLIENT_SECRET
Attioclient ID, client secretATTIO_CLIENT_ID, ATTIO_CLIENT_SECRET
Cal.comclient IDCALCOM_CLIENT_ID
Shopifyclient ID, client secretSHOPIFY_CLIENT_ID, SHOPIFY_CLIENT_SECRET
TrelloAPI keyTRELLO_API_KEY

Validation Checklist

  • BETTER_AUTH_URL and NEXT_PUBLIC_APP_URL match the real public origin
  • all required redirect URIs are registered in the provider app
  • the client ID, client secret, or API key is stored in the correct Aptlystar env var
  • the provider app has the scopes Aptlystar expects
  • the integration can be connected from Settings → Integrations
  • token refresh or reconnect works after the initial connection

Keep This Page Updated

Update this page whenever:

  • a new provider is added in apps/aptlystar/lib/auth/auth.ts
  • a provider ID changes, because the callback path changes
  • env var names change in apps/aptlystar/lib/core/config/env.ts
  • scopes change in apps/aptlystar/lib/oauth/oauth.ts
PreviousIntegrations
NextGoogle Service Accounts

On this page

What You Need From Each Provider
How Redirect URIs Work In Aptlystar
Environment Examples
The Basic Workflow
Provider Groups At A Glance
Shared Provider Apps
Google Cloud
Microsoft Entra ID
Atlassian
Confluence
Jira
One Provider App Per Integration
Slack
Notion
Monday.com
Airtable
HubSpot
Salesforce
Linear
Box
Dropbox
Asana
Pipedrive
Wealthbox
LinkedIn
Reddit
Webflow
X
Zoom
Spotify
WordPress.com
DocuSign
Attio
Cal.com
Shopify
Trello
Quick Reference Matrix
Validation Checklist
Keep This Page Updated