Rename your org

If you’re an org admin who mis-typed your org slug at sign-up, rebranded, or need to align Upwarden with a renamed identity-provider org, this guide walks through the rename. Most of the surface is automatic — the rename rewrites your dashboard URL, the admin API URL, your blocklist source IDs, and the Stytch mirror — but the changes that ride on the slug from outside Upwarden (bookmarks, CI scripts, integration webhooks) need a human to update them.

Before you rename

Two things to know before you click “Rename”.

1. A rename is rate-limited. One rename per org per 24 hours. If you rename twice in quick succession (typo → fix → rebrand), you’ll have to wait the 24h window between the second and third change.
2. The previous slug is blocked from reuse for 30 minutes. Once you rename acme → acme-prod, no other org (and not even your own) can claim the slug acme for 30 minutes. This is the cache-convergence safety window — see Recovery from a wrong rename.

The 30-minute reuse-block window is configurable via VANGUARD_SLUG_REUSE_BLOCK_MIN on self-hosted deployments. The 24h rate limit is fixed at one rename per tenant per day. Self-hosted operators can tune the reuse-block window and the 6-month history retention; ask your operator for the current values if you’re on a self-hosted instance.

Rename from the dashboard

1. Open /admin/ui/orgs/<current-slug>/settings.
2. Find the Rename organisation panel in the Danger zone.
3. Type the new slug. Allowed characters: lowercase alphanumeric + hyphen. Length: 1–128 characters. First character must be alphanumeric.
4. Type the new slug a second time into the typed-confirmation field. The Rename button only enables on an exact match.
5. Step-up auth fires — Upwarden prompts for a passkey (or your second factor if you haven’t enrolled a passkey yet). This is the same step-up that gates webhook secret rotation and Stytch org binding.
6. Click Rename. On success the dashboard redirects to /admin/ui/orgs/<new-slug>/settings and shows a flash banner: “Renamed <old> → <new>. Old URLs will redirect for 6 months.”

What the rename updates

Upwarden handles these surfaces automatically:

• Dashboard URLs. Every /admin/ui/orgs/<old-slug>/* URL 301-redirects to the new slug for GETs. Bookmarks keep working; the redirect lives in the tenant_slug_history table.
• Admin API URLs. /api/v1/admin/orgs/<old-slug>/* GETs 301-redirect. For non-idempotent verbs (POST, PUT, PATCH, DELETE) the resolver renders a transitional click-through page rather than silently replaying your request against the new URL — confirm + resubmit at the new URL.
• Blocklist source IDs. Custom blocklist entries you created via /api/v1/orgs/<old-slug>/blocklist carry an <old-slug>-<uuid> source id. The rename rewrites every such row to <new-slug>-<uuid> inside the same transaction so source-id lookups keep matching.
• Stytch mirror. Upwarden mirrors the new slug to your Stytch organisation in the same transaction. If the Stytch update fails (rare), the local rename still commits and SREs follow up with a manual re-sync; see Stytch drift.
• Webhook event. An org_renamed audit row is written, and a webhook event of the same name is dispatched to every webhook subscriber on the tenant. The payload carries {old_slug, new_slug, renamed_by, renamed_at}. See docs/customer/guides/webhook-events.md for the full event reference.
• Notification email. Every member of the org receives a one-time email confirming the rename. The email links to the new dashboard URL and explains the 6-month redirect window.

What the rename does NOT update

These surfaces ride the slug from outside Upwarden, so you need to update them yourself:

• Bookmarks in your team’s browser. The 301 redirect handles GET URLs, but if you want to drop the indirection, update the bookmark to the new slug.
• CI scripts that hit the admin API. A curl against /api/v1/admin/orgs/<old-slug>/... still works via the redirect, but updating the script to the new slug skips the resolver layer.
• Triggers webhook URLs. Webhook subscribers that hit /triggers/webhook?orgSlug=<old-slug> get an explicit transition response with a warning; update the URL to the new slug. See docs/customer/start/triggers-webhook.md.
• Documentation, runbooks, dashboards. Any external doc that hard-codes your org slug needs a manual update.
• Audit log entries from before the rename. Audit rows are forward-only — historical rows continue to carry the old slug in their event strings (e.g. tier:acme, stytch_binding:acme). Queries against /admin/ui/orgs/<new-slug>/audit surface all historical rows for the tenant including those tagged with the old slug, because audit queries scope by tenant ID rather than by the slug string.
• Already-issued auth sessions. Upwarden’s session JWT carries the Stytch organisation ID, not the slug, so a member signed in before the rename stays signed in across the rename — no re-auth required.

The 6-month redirect window

The tenant_slug_history row written at rename time keeps the redirect alive for 6 months by default. After 6 months the row is pruned by a nightly sweep job and the redirect breaks — requests to /admin/ui/orgs/<old-slug>/* start 404’ing rather than 301’ing.

Plan accordingly:

• Update bookmarks + CI within the first month if you can.
• Communicate the new slug to anyone outside your org (auditors, integration partners) at rename time.
• If a long-term archival CI job hard-codes the old slug, give it the new slug before the 6-month window expires.

Self-hosted operators can extend the window via VANGUARD_SLUG_HISTORY_RETENTION_MONTHS — see the operator runbook for the trade-off (longer retention vs row count growth).

Recovery from a wrong rename

If you renamed to the wrong thing:

• Within the 30-minute reuse-block window: wait until the window expires, then rename back. Within the window, the original slug is reserved against accidental hijack by another tenant — including you. The dashboard surfaces a 409 error if you try to rename back too soon, with the remaining wait time in the response.
• After the reuse-block window expires (after 30 minutes, before the 24h rate limit): rename back from the same Rename organisation panel. The rename helper writes a fresh tenant_slug_history row for the new → previous transition.
• After 24 hours since the wrong rename: rename back normally — no waiting period beyond the still-applicable 30-minute reuse-block window.

Note that an A → B → A rename sequence does NOT delete the A → B history row. Both transitions are preserved in tenant_slug_history for the 6-month retention window. If you renamed in a tight loop (typo → fix), the audit log captures every transition.

Stytch drift

In the rare case that the Stytch slug update fails after the local rename commits, Upwarden:

1. Emits an org_renamed_stytch_drift audit row.
2. Logs a structured WARN in the deployment logs that your SREs alert on.
3. Returns a 502 to the rename request even though the local rename succeeded.

For self-hosted operators, the runbook covers the manual sync command. For Upwarden-hosted customers, SREs re-sync automatically; the only visible effect is that your Stytch dashboard may show the old slug for up to a few hours.

Webhook payload

If you subscribe to webhooks for your org, the rename emits an org_renamed event:

{
  "event": "org_renamed",
  "tenant_id": "<stable UUID, unchanged by rename>",
  "old_slug": "acme",
  "new_slug": "acme-prod",
  "renamed_by": "user:usr-test-...",
  "renamed_at": "2026-06-05T12:34:56Z"
}

Consumers should index on tenant_id (stable across the rename) rather than on old_slug / new_slug (which change). If your integration keys data by slug, the org_renamed event is the signal to rotate the key.

Who can rename

Members with members:w on the tenant — owner and admin roles by default — can rename. The rename also requires step-up auth (rename_org in the sensitive-ops registry), so a stolen long-lived session can’t drive a rename without re-asserting strong factor.

The rename is gated on the Org tier and above: Free and Team tier customers see the panel but the Rename button surfaces an upgrade prompt. Self-hosted deployments can lift the gate by adding org_rename to the relevant tier in config/tier-features.json.