# OAuth applications

OAuth configuration has two distinct owners:

1. **The site owner** creates one provider application for the JustFlows installation and stores its shared client credentials in `Admin → Settings → Integrations`.
2. **The workspace user** opens the workspace Integrations page and authorizes that shared application for a specific account or workspace.

<Info>
Complete the platform setup before asking customers to connect an OAuth provider. Workspace users cannot access the admin credential fields and should never be sent a client secret.
</Info>

## Before creating provider applications

- Set the final HTTPS App URL under `Admin → Settings → General`. Callback URLs are generated from that URL.
- For a public development tunnel, set `INTEGRATION_OAUTH_BASE_URL` to the same public HTTPS origin before copying callback URLs.
- Use a separate provider application and credentials for production, staging, and local/tunnel environments.
- Register every callback exactly as displayed, including scheme, hostname, port, path, and trailing-slash behavior.
- Store secrets only in the JustFlows admin settings or server environment. Do not place them in workspace documentation, screenshots, logs, tickets, or source control.

## Google OAuth Web Client

1. Open [Google Cloud Console](https://console.cloud.google.com/) and select the project used by this JustFlows installation.
2. Configure the OAuth consent screen and choose the publishing/audience mode appropriate for your customers.
3. Open `Google Auth Platform → Clients`. In older navigation, use `APIs & Services → Credentials`.
4. Create or open an OAuth client whose application type is `Web application`.
5. In JustFlows, open the `Google OAuth` tab under `Admin → Settings → Integrations` and copy each callback URL for the Google integrations you intend to offer.
6. Add every copied URL to the Google client's `Authorized redirect URIs`.
7. Copy the Google `Client ID` and `Client secret` into the same JustFlows tab and save.

Enable the corresponding APIs in the Google project: Gmail API, Google Calendar API, Google Sheets API, Google Drive API, Google Photos Library API, and the Google Analytics Data and Admin APIs. Only enable providers you intend to make available.

<Warning>
A Google `redirect_uri_mismatch` means the URL sent by JustFlows is not an exact match for an authorized redirect URI. Check the origin, port, path, tunnel URL, and environment before rotating credentials.
</Warning>

## Microsoft OAuth

1. Open the [Microsoft Entra admin center](https://entra.microsoft.com/) and create or open the web application used by JustFlows.
2. Copy its `Application (client) ID`, create a client secret under `Certificates & secrets`, and copy the secret value immediately.
3. Open `Admin → Settings → Integrations → Microsoft OAuth` in JustFlows. Copy the Outlook and Microsoft Teams callback URLs into the Entra application as Web redirect URIs.
4. Save the client ID and secret in JustFlows. For a single-tenant application, also save its `Directory (tenant) ID`; use `organizations` only when the registration supports organizational directories.
5. For Outlook, add delegated Microsoft Graph permissions `offline_access`, `User.Read`, `Mail.Send`, and `Mail.ReadWrite`.
6. For Teams, add `User.Read`, `Team.ReadBasic.All`, `Channel.ReadBasic.All`, `ChannelMessage.Read.All`, and `ChannelMessage.Send`.
7. Grant tenant admin consent where your Microsoft policy or the requested Teams permissions require it.

## Other OAuth providers

Each provider uses the same ownership pattern: create the shared application, register the callback displayed in its JustFlows admin tab, configure only the permissions the integration needs, then save the issued client ID and secret in JustFlows.

### Slack

1. Create or open the platform app at [Slack API Apps](https://api.slack.com/apps).
2. Under `OAuth & Permissions`, add the bot scopes required by the enabled workflow actions. The current integration can use `chat:write`, `channels:read`, `channels:join`, `channels:manage`, `groups:read`, and `groups:write`.
3. Open `Admin → Settings → Integrations → Slack OAuth`, copy the callback URL, and add it to the Slack app's OAuth redirect URLs.
4. Copy the Slack client ID and client secret into the same JustFlows tab and save.

Workspace connections store their own issued bot token and, when verified callbacks or approvals are used, the Slack signing secret. Configure the workspace's displayed interactivity URL under `Interactivity & Shortcuts`.

### Notion

1. Create or open a **public** integration at [Notion integrations](https://www.notion.so/my-integrations). Internal integrations use workspace tokens and do not use this platform OAuth configuration.
2. Enable OAuth for the public integration.
3. Copy the callback from `Admin → Settings → Integrations → Notion OAuth` into Notion's redirect URI setting.
4. Copy the OAuth client ID and client secret into JustFlows and save.

OAuth authorization does not automatically expose all Notion content. Each workspace must still share the required pages and databases with the connected integration.

### Airtable

1. Open Airtable Builder Hub and register or edit the OAuth integration used by the platform.
2. Add `data.records:read`, `data.records:write`, and `schema.bases:read`. Add `schema.bases:write` only if a future customization creates tables or fields.
3. Copy the callback from `Admin → Settings → Integrations → Airtable OAuth` into the integration's redirect URL list.
4. Save the Airtable client ID and client secret in JustFlows.

During authorization, workspace users must select the Airtable workspaces or bases the connection may access. Provider scopes alone do not grant resource access.

### HubSpot

1. Create or open an app in a [HubSpot developer account](https://developers.hubspot.com/) and open its Auth settings.
2. Register the callback displayed under `Admin → Settings → Integrations → HubSpot OAuth`.
3. Configure `oauth` and the read/write scopes used by the integration: contacts, companies, deals, and tickets.
4. Copy the app client ID and client secret into JustFlows and save.

The user installing the app must have permission to authorize it for the selected HubSpot portal. A HubSpot Super Admin may need to approve or perform the installation.

### Typeform

1. Open [Typeform admin](https://admin.typeform.com/), go to `Developer apps`, and create or open the platform app.
2. Configure `offline`, `accounts:read`, `forms:read`, `responses:read`, `webhooks:read`, and `webhooks:write`.
3. Copy the callback from `Admin → Settings → Integrations → Typeform OAuth` into the app's redirect URL list.
4. Save the Typeform client ID and client secret in JustFlows.

Typeform requires public HTTPS URLs for new webhooks. A local installation therefore needs a tunnel whose public origin matches the callback generated by JustFlows.

### Shopify

1. Create an app in the [Shopify Partner Dashboard](https://partners.shopify.com/) that can use OAuth with merchant stores.
2. Set its App URL to the JustFlows workspace integration page, using the production HTTPS domain.
3. Copy the callback from `Admin → Settings → Integrations → Shopify OAuth` into `Allowed redirection URL(s)`.
4. Configure `read_products`, `read_orders`, `read_customers`, and `write_draft_orders`.
5. Save the app client ID and client secret in JustFlows.

<Warning>
Orders, customers, draft orders, refunds, transactions, shipping, and fulfillment can require Shopify protected-customer-data approval. Request only the data and fields the shipped workflows actually use.
</Warning>

### Calendly

1. Create an OAuth application in the Calendly developer portal.
2. Copy the callback from `Admin → Settings → Integrations → Calendly OAuth` into Calendly. The HTTPS origin and path must match exactly.
3. Copy the client ID, client secret, and the one-time webhook signing key into JustFlows before leaving the provider setup screen.
4. Save the admin settings and keep the signing key protected; JustFlows uses it to verify inbound booking events.

Use a publicly reachable HTTPS base URL for OAuth and webhook testing. Workflow-specific Calendly webhook subscriptions are created later from the workspace workflow setup.

### LinkedIn

1. Create or open the LinkedIn application used by the JustFlows installation.
2. Enable `Sign In with LinkedIn using OpenID Connect` and `Share on LinkedIn` for member-profile publishing.
3. For Company Page publishing, request Community Management access and the organization permissions required by the app.
4. Register the callback shown under `Admin → Settings → Integrations → LinkedIn OAuth`.
5. Save the LinkedIn client ID and client secret in JustFlows.

LinkedIn access tokens commonly require periodic workspace reconnection. Test both member and organization publishing paths before making Company Page actions available.

### Instagram

1. Create a Meta application and add the Instagram API product using Instagram Login.
2. Request `instagram_business_basic`, `instagram_business_content_publish`, and `instagram_business_manage_comments`.
3. Add the callback from `Admin → Settings → Integrations → Instagram OAuth` to the app's allowed OAuth redirect URLs.
4. Save the Meta app ID as the client ID and the app secret as the client secret in JustFlows.

Publishing requires an Instagram Business or Creator account and a public media URL that Meta can download. Personal Instagram accounts are not supported by these actions.

### Sentry

1. Create an OAuth application from the settings of the Sentry organization used for platform testing.
2. Use `org:read`, `project:read`, and `event:read` for read-only triage. Add `event:write` only when workflows may resolve, ignore, assign, or prioritize issues.
3. Register the callback from `Admin → Settings → Integrations → Sentry OAuth`.
4. Save the Sentry client ID and client secret in JustFlows.

Regional Sentry organizations may use a regional API base URL at the workspace connection level; that is separate from the shared OAuth client configuration.

### Zendesk

1. In Zendesk Admin Center, open `Apps and integrations → APIs → Zendesk API → OAuth Clients`.
2. Create a client for the JustFlows installation and register the callback from `Admin → Settings → Integrations → Zendesk OAuth`.
3. Save the Zendesk unique identifier as the client ID and save the issued secret in JustFlows.

Each workspace supplies its own Zendesk subdomain when connecting. The shared OAuth client should be tested against a non-production support account before customer rollout.

## Verify the platform setup

1. Save the admin settings without exposing the credentials to a workspace user.
2. From a test workspace, open the provider on the Integrations page and start its OAuth flow.
3. Confirm the provider consent screen returns to the expected JustFlows hostname and creates the workspace connection.
4. Run the integration's safe connection test, then exercise one non-destructive read action before enabling it for customer plans.