From 42d93ad5a4115bd9b363e265d2af61ad6e82fed6 Mon Sep 17 00:00:00 2001 From: Kentaro Wakayama Date: Thu, 13 Aug 2026 14:35:14 +0200 Subject: [PATCH 1/4] docs: add provider integration setup guides --- docs/concepts/salesforce-integration.md | 3 + docs/guides/index.md | 23 ++++--- docs/guides/integrations.md | 21 ++++++ docs/guides/integrations/github.md | 47 +++++++++++++ docs/guides/integrations/jira.md | 50 ++++++++++++++ docs/guides/integrations/salesforce.md | 90 +++++++++++++++++++++++++ tests/docs/guide-contracts.test.ts | 19 ++++++ 7 files changed, 243 insertions(+), 10 deletions(-) create mode 100644 docs/guides/integrations/github.md create mode 100644 docs/guides/integrations/jira.md create mode 100644 docs/guides/integrations/salesforce.md diff --git a/docs/concepts/salesforce-integration.md b/docs/concepts/salesforce-integration.md index 6947a0158a..26c2477087 100644 --- a/docs/concepts/salesforce-integration.md +++ b/docs/concepts/salesforce-integration.md @@ -12,6 +12,9 @@ useful provider surface for generic Salesforce access. The reason to route Salesforce through Veryfront is that customer support agents need a governed workflow surface, not only a raw CRM protocol surface. +For installation, OAuth, and service-account setup, see +[Set up Salesforce](../guides/integrations/salesforce.md). + ## The design choice Salesforce owns CRM data and CRM permissions. Veryfront owns the agent runtime: diff --git a/docs/guides/index.md b/docs/guides/index.md index 4515dc5b1f..963063c9a5 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -64,13 +64,16 @@ details, see [API reference](../api-reference/index.md). ## Connect external systems -| Goal | Guide | -| -------------------------------------------------- | ----------------------------------- | -| Sign users in with OAuth | [OAuth](./oauth.md) | -| Add connector-backed service tools | [Integrations](./integrations.md) | -| Expose tools, prompts, and resources to assistants | [MCP server](./mcp-server.md) | -| Connect coding agents to the dev server | [Coding agents](./coding-agents.md) | -| Run isolated commands or file operations | [Sandbox](./sandbox.md) | +| Goal | Guide | +| -------------------------------------------------- | ------------------------------------------ | +| Sign users in with OAuth | [OAuth](./oauth.md) | +| Add connector-backed service tools | [Integrations](./integrations.md) | +| Set up GitHub | [GitHub](./integrations/github.md) | +| Set up Jira | [Jira](./integrations/jira.md) | +| Set up Salesforce | [Salesforce](./integrations/salesforce.md) | +| Expose tools, prompts, and resources to assistants | [MCP server](./mcp-server.md) | +| Connect coding agents to the dev server | [Coding agents](./coding-agents.md) | +| Run isolated commands or file operations | [Sandbox](./sandbox.md) | ## Deploy and extend @@ -86,6 +89,6 @@ details, see [API reference](../api-reference/index.md). ## Troubleshoot -| Goal | Guide | -| ----------------------------------- | --------------------------------- | -| Look up an error slug you were shown | [Error reference](./errors.md) | +| Goal | Guide | +| ------------------------------------ | ------------------------------ | +| Look up an error slug you were shown | [Error reference](./errors.md) | diff --git a/docs/guides/integrations.md b/docs/guides/integrations.md index 320f573a15..18dd988cac 100644 --- a/docs/guides/integrations.md +++ b/docs/guides/integrations.md @@ -146,6 +146,17 @@ No OAuth connect step is shown for these connectors. The integration runtime resolves their credentials during tool execution; agents do not receive raw secrets. +## Set up a provider + +Use a provider guide when a connector needs provider-specific installation, +permissions, OAuth configuration, or service-account credentials. + +| Provider | Guide | +| ---------- | ------------------------------------------------- | +| GitHub | [Set up GitHub](./integrations/github.md) | +| Jira | [Set up Jira](./integrations/jira.md) | +| Salesforce | [Set up Salesforce](./integrations/salesforce.md) | + ## Available integrations The built-in connector catalog contains 204 connectors. The supported set is @@ -176,3 +187,13 @@ when you need exact exported names or icon metadata: 4. Confirm the run retries the tool and receives a non-error result. 5. Reload the project and confirm connection inventory still reports the connection independently of agent source and both policy layers. + +## Next + +- [Set up GitHub](./integrations/github.md) +- [Set up Jira](./integrations/jira.md) +- [Set up Salesforce](./integrations/salesforce.md) + +## Related + +- [veryfront/integrations](../api-reference/veryfront/integrations.md): Connector catalog and helper API. diff --git a/docs/guides/integrations/github.md b/docs/guides/integrations/github.md new file mode 100644 index 0000000000..b905df09ea --- /dev/null +++ b/docs/guides/integrations/github.md @@ -0,0 +1,47 @@ +--- +title: "Set up GitHub" +description: "Connect a GitHub account to Veryfront for repository, issue, and pull-request tools." +order: 51 +--- + +Use GitHub OAuth when an agent needs repository, issue, or pull-request tools. + +## Connect a GitHub user + +1. In Veryfront, open the project that needs GitHub tools. +2. Start the GitHub connection from the integration prompt or project integration settings. +3. Sign in to GitHub and approve the requested access. +4. Run a read-only GitHub tool, such as listing repositories, to verify the connection. + +Managed GitHub OAuth works without project credentials. Set project credentials +only when the project must use its own GitHub OAuth app for custom consent +branding, verification, or scope requirements. + +## Use your own GitHub OAuth app + +1. In [GitHub Developer Settings](https://github.com/settings/developers), create an OAuth App. +2. Add the Veryfront callback URL for the target environment. +3. Set the OAuth app client ID and client secret as project environment variables: + +| Variable | Value | +| ---------------------- | ------------------------------ | +| `GITHUB_CLIENT_ID` | GitHub OAuth App client ID | +| `GITHUB_CLIENT_SECRET` | GitHub OAuth App client secret | + +Keep the secret in your approved secret manager. Never place it in agent +prompts, project files, tickets, or client-side environment variables. + +## Verify it worked + +1. Start a new agent run that uses a read-only GitHub tool. +2. Confirm the tool returns the connected user's GitHub data. + +## Next + +- [Integrations](../integrations.md): Declare GitHub tools and apply source or project policy. +- [Set up Jira](./jira.md): Connect a Jira provider. +- [Set up Salesforce](./salesforce.md): Connect a Salesforce provider. + +## Related + +- [veryfront/integrations](../../api-reference/veryfront/integrations.md): Connector catalog and helper API. diff --git a/docs/guides/integrations/jira.md b/docs/guides/integrations/jira.md new file mode 100644 index 0000000000..7b8e86772a --- /dev/null +++ b/docs/guides/integrations/jira.md @@ -0,0 +1,50 @@ +--- +title: "Set up Jira" +description: "Connect an Atlassian account to Veryfront for Jira project and issue tools." +order: 52 +--- + +Use Jira OAuth when an agent needs to read or update Jira projects and issues. + +## Connect a Jira user + +1. In Veryfront, open the project that needs Jira tools. +2. Start the Jira connection from the integration prompt or project integration settings. +3. Sign in to Atlassian and approve the requested access. +4. Run a read-only Jira tool, such as listing accessible sites or projects, to verify the connection. + +Managed Atlassian OAuth works without project credentials. Set project +credentials only when the project must use its own Atlassian OAuth app. + +## Use your own Atlassian OAuth app + +1. In the [Atlassian developer console](https://developer.atlassian.com/console/myapps/), create an OAuth 2.0 app. +2. Add the Veryfront callback URL for the target environment. +3. Grant the Jira scopes required by the project: `read:jira-work`, `write:jira-work`, `read:jira-user`, and `offline_access`. +4. Set the OAuth app client ID and client secret as project environment variables: + +| Variable | Value | +| ------------------------- | ----------------------------- | +| `ATLASSIAN_CLIENT_ID` | Atlassian OAuth client ID | +| `ATLASSIAN_CLIENT_SECRET` | Atlassian OAuth client secret | + +Set `JIRA_CLOUD_ID` when the connected user has access to more than one +Atlassian site. Obtain the site ID from the list-sites tool result. + +Keep the secret in your approved secret manager. Never place it in agent +prompts, project files, tickets, or client-side environment variables. + +## Verify it worked + +1. Start a new agent run that uses a read-only Jira tool. +2. Confirm the tool returns the expected Atlassian site or Jira project data. + +## Next + +- [Integrations](../integrations.md): Declare Jira tools and apply source or project policy. +- [Set up GitHub](./github.md): Connect a GitHub provider. +- [Set up Salesforce](./salesforce.md): Connect a Salesforce provider. + +## Related + +- [veryfront/integrations](../../api-reference/veryfront/integrations.md): Connector catalog and helper API. diff --git a/docs/guides/integrations/salesforce.md b/docs/guides/integrations/salesforce.md new file mode 100644 index 0000000000..388085eb02 --- /dev/null +++ b/docs/guides/integrations/salesforce.md @@ -0,0 +1,90 @@ +--- +title: "Set up Salesforce" +description: "Install and connect the Veryfront Salesforce integration with per-user OAuth or a service account." +order: 50 +--- + +Use this guide to connect a Salesforce org to Veryfront. Choose per-user OAuth +when each action must use an individual's Salesforce access. Choose a service +account for scheduled or project-owned automation. + +## Prerequisites + +- A Salesforce administrator for the target org. +- A Veryfront project with Salesforce tools declared in an agent. +- Salesforce enabled for the target Veryfront environment. Salesforce is currently feature-gated. Set `VERYFRONT_EXPERIMENTAL_INTEGRATIONS=salesforce` where the integration catalog is configured. + +## Connect a Salesforce user + +Install the **Veryfront Salesforce Integration** package in each Salesforce +org that users connect to Veryfront. Salesforce External Client Apps are scoped +to an org. Without the installed package, Salesforce rejects a cross-org +authorization request. + +1. Sign in to the Salesforce org as an administrator. +2. Open the [Veryfront Salesforce Integration beta installation page](https://login.salesforce.com/packaging/installPackage.apexp?p0=04tfj000000RX37AAG). +3. Select **Install for Admins Only** and acknowledge that the application is not distributed through AppExchange. +4. Wait for the installation to complete. +5. In Salesforce Setup, open **External Client App Manager** and select **Veryfront**. +6. Confirm that the app is **Packaged (Installed)** and **Enabled**. +7. Under **Policies**, select the permitted-users policy. The beta package permits all users to self-authorize. Restrict access to the required profile or permission set when the org uses a tighter access policy. + +Install the beta package in a sandbox or test org before installing it in a +production Salesforce org. + +In Veryfront, open the project and start the Salesforce connection from the +integration prompt or project integration settings. Sign in to the Salesforce +org where the package is installed, approve consent, then run a read-only +Salesforce tool to verify access. + +Never paste a Salesforce consumer secret into an agent prompt, project file, +ticket, or client-side environment variable. + +## Use a service account + +Use a service account when a run needs non-interactive access. Veryfront uses +Salesforce OAuth client credentials and executes as the Connected App's +dedicated **Run As** integration user. It does not open browser consent or use +a user's personal OAuth token. + +In the target Salesforce org: + +1. Create a dedicated integration user with the minimum object, field, and API permissions required by the project. +2. Create or configure a Salesforce Connected App for the client-credentials flow. +3. Set the integration user as the Connected App's **Run As** user. +4. Record the Connected App consumer key and consumer secret in your approved secret manager. + +Set all three values as project environment variables in the matching +Veryfront environment: + +| Variable | Value | +| ------------------------------------------ | ------------------------------ | +| `SALESFORCE_SERVICE_ACCOUNT_CLIENT_ID` | Connected App consumer key | +| `SALESFORCE_SERVICE_ACCOUNT_CLIENT_SECRET` | Connected App consumer secret | +| `SALESFORCE_SERVICE_ACCOUNT_LOGIN_URL` | `https://login.salesforce.com` | + +For a Salesforce sandbox, set `SALESFORCE_SERVICE_ACCOUNT_LOGIN_URL` to +`https://test.salesforce.com`. Use the Salesforce login endpoint, not the +instance URL returned after authentication. + +All three variables are required. If any service-account variable is missing, +Veryfront fails closed and does not fall back to a human OAuth connection for +non-interactive runs. Rotate the consumer secret in Salesforce and update the +project environment variable through the approved secret-management workflow. + +## Verify it worked + +1. Start a new agent run that uses a read-only Salesforce tool, such as account or case lookup. +2. Confirm the tool returns data from the target Salesforce org. +3. For a service account, confirm the Salesforce audit trail attributes the request to the configured integration user. + +## Next + +- [Integrations](../integrations.md): Declare Salesforce tools and apply source or project policy. +- [Set up GitHub](./github.md): Connect a GitHub provider. +- [Set up Jira](./jira.md): Connect a Jira provider. + +## Related + +- [veryfront/integrations](../../api-reference/veryfront/integrations.md): Connector catalog and helper API. +- [Salesforce integration](../../concepts/salesforce-integration.md): Why Veryfront uses a governed Salesforce integration layer. diff --git a/tests/docs/guide-contracts.test.ts b/tests/docs/guide-contracts.test.ts index 491271057d..bb50d4fbf7 100644 --- a/tests/docs/guide-contracts.test.ts +++ b/tests/docs/guide-contracts.test.ts @@ -553,6 +553,25 @@ const GUIDE_CONTRACTS: Record = { "Available integrations", ], }, + "guides/integrations/github.md": { + references: ["../../api-reference/veryfront/integrations.md"], + snippets: ["Connect a GitHub user", "GITHUB_CLIENT_ID", "Verify it worked"], + }, + "guides/integrations/jira.md": { + references: ["../../api-reference/veryfront/integrations.md"], + snippets: ["Connect a Jira user", "ATLASSIAN_CLIENT_ID", "JIRA_CLOUD_ID"], + }, + "guides/integrations/salesforce.md": { + references: [ + "../../api-reference/veryfront/integrations.md", + "../../concepts/salesforce-integration.md", + ], + snippets: [ + "Connect a Salesforce user", + "SALESFORCE_SERVICE_ACCOUNT_CLIENT_ID", + "Verify it worked", + ], + }, "guides/runs.md": { references: ["../api-reference/veryfront/runs.md"], snippets: [ From 6ef29e3e11944f1305ba27be81bea032a4a95b7a Mon Sep 17 00:00:00 2001 From: Kentaro Wakayama Date: Thu, 13 Aug 2026 17:38:04 +0200 Subject: [PATCH 2/4] docs: clarify provider integration setup --- docs/guides/integrations/github.md | 11 +++++++-- docs/guides/integrations/jira.md | 12 ++++++++-- docs/guides/integrations/salesforce.md | 31 ++++++++++++++++---------- tests/docs/guide-contracts.test.ts | 17 ++++++++++++-- 4 files changed, 53 insertions(+), 18 deletions(-) diff --git a/docs/guides/integrations/github.md b/docs/guides/integrations/github.md index b905df09ea..7486763bdc 100644 --- a/docs/guides/integrations/github.md +++ b/docs/guides/integrations/github.md @@ -20,8 +20,15 @@ branding, verification, or scope requirements. ## Use your own GitHub OAuth app 1. In [GitHub Developer Settings](https://github.com/settings/developers), create an OAuth App. -2. Add the Veryfront callback URL for the target environment. -3. Set the OAuth app client ID and client secret as project environment variables: +2. Add the exact callback URL for the target environment: + - Production: `https://api.veryfront.com/oauth/callback/github` + - Staging: `https://api.veryfront.org/oauth/callback/github` +3. For another environment, copy the callback URL displayed by its Veryfront + OAuth connection flow. A GitHub OAuth App can serve more than one route only + when GitHub's host, port, and callback-path rules accept the route. The + hosted production and staging URLs above do not share a base host, so use + separate OAuth Apps for them. +4. Set the OAuth app client ID and client secret as project environment variables: | Variable | Value | | ---------------------- | ------------------------------ | diff --git a/docs/guides/integrations/jira.md b/docs/guides/integrations/jira.md index 7b8e86772a..772958a695 100644 --- a/docs/guides/integrations/jira.md +++ b/docs/guides/integrations/jira.md @@ -19,8 +19,16 @@ credentials only when the project must use its own Atlassian OAuth app. ## Use your own Atlassian OAuth app 1. In the [Atlassian developer console](https://developer.atlassian.com/console/myapps/), create an OAuth 2.0 app. -2. Add the Veryfront callback URL for the target environment. -3. Grant the Jira scopes required by the project: `read:jira-work`, `write:jira-work`, `read:jira-user`, and `offline_access`. +2. Add the exact callback URL for the target environment: + - Production: `https://api.veryfront.com/oauth/callback/jira` + - Staging: `https://api.veryfront.org/oauth/callback/jira` +3. Grant all four scopes that the Jira connector requests by default: + - `read:jira-work` for Jira reads. + - `write:jira-work` for write tools. + - `read:jira-user` for `jira__search_users`. + - `offline_access` to receive refresh tokens. Veryfront uses refresh tokens + to keep a user connection active; omit it only when the connection must + not be refreshable. 4. Set the OAuth app client ID and client secret as project environment variables: | Variable | Value | diff --git a/docs/guides/integrations/salesforce.md b/docs/guides/integrations/salesforce.md index 388085eb02..9560f8dc31 100644 --- a/docs/guides/integrations/salesforce.md +++ b/docs/guides/integrations/salesforce.md @@ -12,7 +12,11 @@ account for scheduled or project-owned automation. - A Salesforce administrator for the target org. - A Veryfront project with Salesforce tools declared in an agent. -- Salesforce enabled for the target Veryfront environment. Salesforce is currently feature-gated. Set `VERYFRONT_EXPERIMENTAL_INTEGRATIONS=salesforce` where the integration catalog is configured. +- The hosted Veryfront API, which supplies the Salesforce provider adapter. The + generic Veryfront runtime cannot scaffold or execute Salesforce OAuth routes. + An embedding host that supplies its own Salesforce adapter must declare + `VERYFRONT_HOST_ADAPTER_INTEGRATIONS=salesforce` to expose the connector + catalog. This does not enable generic Salesforce scaffolding. ## Connect a Salesforce user @@ -51,21 +55,24 @@ In the target Salesforce org: 1. Create a dedicated integration user with the minimum object, field, and API permissions required by the project. 2. Create or configure a Salesforce Connected App for the client-credentials flow. -3. Set the integration user as the Connected App's **Run As** user. -4. Record the Connected App consumer key and consumer secret in your approved secret manager. +3. Enable **Client Credentials Flow** and select the **Manage user data via APIs** (`api`) OAuth scope. +4. In the Connected App policy, set permitted users to **Admin approved users are pre-authorized**, then select the dedicated integration user as the **Run As** user. +5. Record the Connected App consumer key and consumer secret in your approved secret manager. Set all three values as project environment variables in the matching Veryfront environment: -| Variable | Value | -| ------------------------------------------ | ------------------------------ | -| `SALESFORCE_SERVICE_ACCOUNT_CLIENT_ID` | Connected App consumer key | -| `SALESFORCE_SERVICE_ACCOUNT_CLIENT_SECRET` | Connected App consumer secret | -| `SALESFORCE_SERVICE_ACCOUNT_LOGIN_URL` | `https://login.salesforce.com` | - -For a Salesforce sandbox, set `SALESFORCE_SERVICE_ACCOUNT_LOGIN_URL` to -`https://test.salesforce.com`. Use the Salesforce login endpoint, not the -instance URL returned after authentication. +| Variable | Value | +| ------------------------------------------ | ----------------------------- | +| `SALESFORCE_SERVICE_ACCOUNT_CLIENT_ID` | Connected App consumer key | +| `SALESFORCE_SERVICE_ACCOUNT_CLIENT_SECRET` | Connected App consumer secret | +| `SALESFORCE_SERVICE_ACCOUNT_LOGIN_URL` | Salesforce My Domain origin | + +Set `SALESFORCE_SERVICE_ACCOUNT_LOGIN_URL` to the target org's Salesforce My +Domain origin, for example `https://acme.my.salesforce.com`. Veryfront rejects +generic login endpoints such as `https://login.salesforce.com` and +`https://test.salesforce.com`; it also rejects paths and non-HTTPS URLs. Use +the My Domain origin, not the instance URL returned after authentication. All three variables are required. If any service-account variable is missing, Veryfront fails closed and does not fall back to a human OAuth connection for diff --git a/tests/docs/guide-contracts.test.ts b/tests/docs/guide-contracts.test.ts index bb50d4fbf7..4c715cf24f 100644 --- a/tests/docs/guide-contracts.test.ts +++ b/tests/docs/guide-contracts.test.ts @@ -555,11 +555,22 @@ const GUIDE_CONTRACTS: Record = { }, "guides/integrations/github.md": { references: ["../../api-reference/veryfront/integrations.md"], - snippets: ["Connect a GitHub user", "GITHUB_CLIENT_ID", "Verify it worked"], + snippets: [ + "Connect a GitHub user", + "https://api.veryfront.com/oauth/callback/github", + "GITHUB_CLIENT_ID", + "Verify it worked", + ], }, "guides/integrations/jira.md": { references: ["../../api-reference/veryfront/integrations.md"], - snippets: ["Connect a Jira user", "ATLASSIAN_CLIENT_ID", "JIRA_CLOUD_ID"], + snippets: [ + "Connect a Jira user", + "https://api.veryfront.com/oauth/callback/jira", + "read:jira-user", + "ATLASSIAN_CLIENT_ID", + "JIRA_CLOUD_ID", + ], }, "guides/integrations/salesforce.md": { references: [ @@ -568,7 +579,9 @@ const GUIDE_CONTRACTS: Record = { ], snippets: [ "Connect a Salesforce user", + "VERYFRONT_HOST_ADAPTER_INTEGRATIONS=salesforce", "SALESFORCE_SERVICE_ACCOUNT_CLIENT_ID", + "Admin approved users are pre-authorized", "Verify it worked", ], }, From 3974a8dad887177134ecb940aaec29f7d3a81e4b Mon Sep 17 00:00:00 2001 From: Kentaro Wakayama Date: Thu, 13 Aug 2026 17:44:58 +0200 Subject: [PATCH 3/4] docs: distinguish hosted OAuth callbacks --- docs/guides/integrations/github.md | 16 ++++++++++------ docs/guides/integrations/jira.md | 7 +++++-- 2 files changed, 15 insertions(+), 8 deletions(-) diff --git a/docs/guides/integrations/github.md b/docs/guides/integrations/github.md index 7486763bdc..c79bc6f2a9 100644 --- a/docs/guides/integrations/github.md +++ b/docs/guides/integrations/github.md @@ -23,12 +23,16 @@ branding, verification, or scope requirements. 2. Add the exact callback URL for the target environment: - Production: `https://api.veryfront.com/oauth/callback/github` - Staging: `https://api.veryfront.org/oauth/callback/github` -3. For another environment, copy the callback URL displayed by its Veryfront - OAuth connection flow. A GitHub OAuth App can serve more than one route only - when GitHub's host, port, and callback-path rules accept the route. The - hosted production and staging URLs above do not share a base host, so use - separate OAuth Apps for them. -4. Set the OAuth app client ID and client secret as project environment variables: +3. These are the hosted Veryfront provider-adapter callbacks. Do not replace + them with the `veryfront/oauth` framework callback path. A self-hosted + framework application instead registers its own `APP_URL` origin with + `/api/auth/github/callback`. +4. For another hosted environment, copy the callback URL displayed by its + Veryfront OAuth connection flow. A GitHub OAuth App can serve more than one + route only when GitHub's host, port, and callback-path rules accept the + route. The hosted production and staging URLs above do not share a base host, + so use separate OAuth Apps for them. +5. Set the OAuth app client ID and client secret as project environment variables: | Variable | Value | | ---------------------- | ------------------------------ | diff --git a/docs/guides/integrations/jira.md b/docs/guides/integrations/jira.md index 772958a695..ded6524513 100644 --- a/docs/guides/integrations/jira.md +++ b/docs/guides/integrations/jira.md @@ -22,14 +22,17 @@ credentials only when the project must use its own Atlassian OAuth app. 2. Add the exact callback URL for the target environment: - Production: `https://api.veryfront.com/oauth/callback/jira` - Staging: `https://api.veryfront.org/oauth/callback/jira` -3. Grant all four scopes that the Jira connector requests by default: +3. These are the hosted Veryfront provider-adapter callbacks. A self-hosted + framework application instead registers its own `APP_URL` origin with + `/api/auth/jira/callback`. +4. Grant all four scopes that the Jira connector requests by default: - `read:jira-work` for Jira reads. - `write:jira-work` for write tools. - `read:jira-user` for `jira__search_users`. - `offline_access` to receive refresh tokens. Veryfront uses refresh tokens to keep a user connection active; omit it only when the connection must not be refreshable. -4. Set the OAuth app client ID and client secret as project environment variables: +5. Set the OAuth app client ID and client secret as project environment variables: | Variable | Value | | ------------------------- | ----------------------------- | From ee908320389348f386ddd13b9d07017992c1c0b1 Mon Sep 17 00:00:00 2001 From: Kentaro Wakayama Date: Thu, 13 Aug 2026 17:54:45 +0200 Subject: [PATCH 4/4] docs: limit custom Jira OAuth to self-hosted --- docs/guides/integrations/jira.md | 19 +++++++++---------- tests/docs/guide-contracts.test.ts | 2 +- 2 files changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/guides/integrations/jira.md b/docs/guides/integrations/jira.md index ded6524513..6a5c8e97a7 100644 --- a/docs/guides/integrations/jira.md +++ b/docs/guides/integrations/jira.md @@ -14,25 +14,24 @@ Use Jira OAuth when an agent needs to read or update Jira projects and issues. 4. Run a read-only Jira tool, such as listing accessible sites or projects, to verify the connection. Managed Atlassian OAuth works without project credentials. Set project -credentials only when the project must use its own Atlassian OAuth app. +credentials only for a self-hosted framework deployment that owns one +distributable Atlassian OAuth app. Hosted Veryfront projects must use the +managed OAuth connection. -## Use your own Atlassian OAuth app +## Use an Atlassian OAuth app in a self-hosted deployment 1. In the [Atlassian developer console](https://developer.atlassian.com/console/myapps/), create an OAuth 2.0 app. -2. Add the exact callback URL for the target environment: - - Production: `https://api.veryfront.com/oauth/callback/jira` - - Staging: `https://api.veryfront.org/oauth/callback/jira` -3. These are the hosted Veryfront provider-adapter callbacks. A self-hosted - framework application instead registers its own `APP_URL` origin with - `/api/auth/jira/callback`. -4. Grant all four scopes that the Jira connector requests by default: +2. Register your deployment's `APP_URL` origin with + `/api/auth/jira/callback`, for example + `https://app.example.com/api/auth/jira/callback`. +3. Grant all four scopes that the Jira connector requests by default: - `read:jira-work` for Jira reads. - `write:jira-work` for write tools. - `read:jira-user` for `jira__search_users`. - `offline_access` to receive refresh tokens. Veryfront uses refresh tokens to keep a user connection active; omit it only when the connection must not be refreshable. -5. Set the OAuth app client ID and client secret as project environment variables: +4. Set the OAuth app client ID and client secret as project environment variables: | Variable | Value | | ------------------------- | ----------------------------- | diff --git a/tests/docs/guide-contracts.test.ts b/tests/docs/guide-contracts.test.ts index 4c715cf24f..902ce43a79 100644 --- a/tests/docs/guide-contracts.test.ts +++ b/tests/docs/guide-contracts.test.ts @@ -566,7 +566,7 @@ const GUIDE_CONTRACTS: Record = { references: ["../../api-reference/veryfront/integrations.md"], snippets: [ "Connect a Jira user", - "https://api.veryfront.com/oauth/callback/jira", + "/api/auth/jira/callback", "read:jira-user", "ATLASSIAN_CLIENT_ID", "JIRA_CLOUD_ID",