# Redirect URL documentation fix — design

**Date:** 2026-04-15
**Area:** `agen-for-work/connectors/`
**Type:** Documentation correction + tooling update

## Problem

All 19 Agen for Work marketplace connector guides under
`agen-for-work/connectors/marketplace/` hardcode an incorrect OAuth Redirect URL:


```
https://api.frontegg.com/app-integrations/resources/integrations-callback/v1/dev-callback
https://api.us.frontegg.com/app-integrations/resources/integrations-callback/v1/dev-callback
```

The correct Redirect URL is a single, tenant-specific value built from the
tenant's MCP Gateway URL (described in `agen-for-work/settings/overview.md`):


```
https://<MCP Gateway URL>/integration-callback
```

When a custom domain is configured, the pattern becomes:


```
https://<custom_domain>/integration-callback
```

Additionally:

- There is no shared reference page explaining how to construct this URL.
- Screenshots in the 19 guides show the wrong URL (typed into real provider UIs),
so text fixes alone are insufficient — the screenshots must be re-captured.
- The `create-integration-doc` skill embeds the same wrong URLs in both its
process instructions and its markdown template, so any future connector guide
inherits the bug.


## Goals

1. Introduce a single source of truth describing how to get the Redirect URL.
2. Replace hardcoded wrong URLs across all 19 marketplace guides with a
placeholder that points users to the shared page.
3. Re-capture all screenshots that show the Redirect URL value inside provider UIs.
4. Update the `create-integration-doc` skill so it produces correct guides going
forward.
5. Keep the change scoped to one PR, split into logical phased commits.


## Non-goals

- No changes to `agen-for-work/settings/overview.md` content (only linking to it).
- No restructuring of connector categories or sidebar groups beyond adding one entry.
- No changes to CIAM or other product documentation — this is Agen for Work only.
- No audit or rework of OAuth scopes in existing guides.


## Design

### 1. New shared page — `agen-for-work/connectors/redirect-url.md`

Purpose: single source of truth for how to construct the Redirect URL.

Structure:

- `## Get your Redirect URL` — intro paragraph, explains the URL is needed when
configuring OAuth applications in third-party services.
- `### URL format` — the formula:

```
https://<MCP Gateway URL>/integration-callback
```
- `### Find your MCP Gateway URL` — short instruction: open **Settings → Basic
configuration**, copy the **MCP Gateway URL** value. Link to
`../settings/overview.md`. One `LightboxImage` screenshot of the Settings page
with the MCP Gateway URL field highlighted.
- `### Using a custom domain` — if a custom domain is configured in Settings,
use:

```
https://<custom_domain>/integration-callback
```
Link to the custom-domain section of `settings/overview.md`.
- `### Example` — one realistic example using a placeholder tenant:
`https://your-tenant.mcp-gw.frontegg.com/integration-callback`.


Formatting must satisfy `scripts/check-content-style.mjs`:
first heading H2, subsequent H3+, sentence case, no emojis, `→` arrows.

### 2. Sidebar update — `agen-for-work/sidebars.yaml`

Add one entry inside the Connectors group, **above** the Marketplace subgroup:


```yaml
- label: Redirect URL
  page: connectors/redirect-url.md
```

Exact placement preserves existing Marketplace ordering.

### 3. Marketplace guides — text changes (19 files)

Affected files (all under `agen-for-work/connectors/marketplace/`):
asana, airtable, clickup, databricks, front, helpscout, hubspot, intercom,
linkedin, monday, pagerduty, servicenow, shopify, surveymonkey, todoist,
twitter, wordpress, zendesk, zoom.

For each file:

- In the step titled **"Configure redirect URI"** / **"Add redirect URL"**
(wording varies per provider), replace the two hardcoded URLs and any
accompanying sentence like *"If the service allows only one redirect URI, use
the first one"* with:

```markdown
Enter your Frontegg Redirect URL:

```
https://<your-mcp-gateway-url>/integration-callback
```
```
- In the `### Additional resources` section at the bottom of the file, add:

```
- [How to get your Redirect URL](../redirect-url.md)
```


No other text or step-numbering changes.

### 4. Screenshot re-capture (19 connectors)

For each connector, identify and regenerate every screenshot that visibly
contains the Redirect URL value (typically in the provider's OAuth settings
page after the URL has been pasted). Screenshots that only show the "Add
redirect URL" button or an empty dialog are left untouched.

Rules (inherited from `.claude/skills/create-integration-doc`):

- Browser window fixed at 1920×1080.
- UI language English.
- Placeholder URL used when typing into provider UI:
`https://your-tenant.mcp-gw.frontegg.com/integration-callback`.
Fallback: if the provider validates the URL and rejects the placeholder, use
the real MCP Gateway URL of the `integrations@frontegg.com` test tenant and
blur the tenant-specific subdomain prefix.
- Existing rules for blur (secrets, emails, unrelated apps), highlight (red
outline on key elements), and file naming (`{integration-id}-N.png`) still
apply.
- Replace files in place at
`agen-for-work/connectors/marketplace/images/{integration-id}-N.png`.


Execute one connector per sub-task; validate the page renders correctly before
moving to the next.

### 5. `create-integration-doc` skill update

File: `.claude/skills/create-integration-doc/SKILL.md` (and referenced templates).

Changes:

- **"OAuth Redirect URIs" default-settings section** — replace the two
hardcoded URLs with a single formula:

```
Redirect URL format: https://<MCP Gateway URL>/integration-callback
```
Add a sentence: *"See `agen-for-work/connectors/redirect-url.md` for the
canonical description — link to it from new guides."*
- **Markdown template in Step 3.1** — rewrite the "Configure redirect URIs"
sample step to match the new pattern (placeholder URL in a code block, no
"if the service allows only one…" sentence).
- **Additional resources section of the template** — add the bullet:
`- [How to get your Redirect URL](../redirect-url.md)`
- **Screenshot guidance** — add a note: when typing the Redirect URL into a
provider's UI for screenshots, prefer
`https://your-tenant.mcp-gw.frontegg.com/integration-callback`; fall back to a
real tenant URL only if the provider rejects the placeholder.
- **Sidebar update instruction** — unchanged (entry still goes under
Marketplace); explicitly note that `redirect-url.md` is a shared page, not a
per-connector page, and must not be duplicated.


### 6. Execution phases (one PR, atomic commits)

1. Create `redirect-url.md` + Settings screenshot + sidebar entry.
2. Bulk text update in 19 marketplace guides (no screenshot changes).
3. Update `create-integration-doc` skill (instructions + template).
4. Re-capture screenshots, one connector per commit (19 commits).
5. Run validation: `npm run test` and `npm run check:content-style`.


### 7. Validation

- `npm run check:content-style` — all 20 updated markdown files must pass.
- `npm run test` — Redocly lint must pass.
- Manual spot-check: open `npm run dev` preview, verify the new page renders,
the sidebar entry appears, and at least 3 marketplace guides link correctly
to `redirect-url.md`.


## Open risks

- **Provider URL validation** — some OAuth providers refuse obviously fake
redirect URIs. Mitigation documented in §4 (fallback to real tenant URL with
blur).
- **Custom domain behaviour** — the spec assumes the Redirect URL path
(`/integration-callback`) is identical under custom domain and default MCP
Gateway URL. If backend behaviour differs, §1 needs a caveat. Confirm with
backend team during phase 1 if uncertain.
- **Screenshot drift** — providers occasionally redesign OAuth settings pages;
re-captures may require small step-text tweaks. Handle per-connector during
phase 4.