From 75219dfeed690456064bc758a98ba9304de99190 Mon Sep 17 00:00:00 2001 From: vinckr Date: Tue, 10 Feb 2026 10:18:23 -0300 Subject: [PATCH 1/2] fix: admin API URLs in local dev --- docs/getting-started/local-development.mdx | 6 +++++- docs/kratos/manage-identities/40_invite-users.mdx | 8 ++++++++ docs/troubleshooting/10_crsf.mdx | 15 +++++++++++++++ 3 files changed, 28 insertions(+), 1 deletion(-) diff --git a/docs/getting-started/local-development.mdx b/docs/getting-started/local-development.mdx index 4db710f86c..5bdc943a40 100644 --- a/docs/getting-started/local-development.mdx +++ b/docs/getting-started/local-development.mdx @@ -104,7 +104,11 @@ available. The `--dev` flag disables a few security checks to make local develop performing the registration flow: [`http://localhost:4000/ui/registration`](http://localhost:4000/ui/registration). You can now start developing locally. Make sure to send any HTTP calls you make to `http://localhost:4000` and not -`https://{your-slug}.projects.oryapis.com`. For example, when you configure the Ory SDK (here in Node.js): +`https://{your-slug}.projects.oryapis.com`. This also applies to URLs returned by Admin API endpoints, such as recovery or +invite links. These URLs point to the project slug domain by default and must be rewritten to the Tunnel URL before use in the +browser. Read [CSRF troubleshooting](../troubleshooting/10_crsf.mdx#admin-api-urls-in-local-development) for more details. + +For example, when you configure the Ory SDK (here in Node.js): ```typescript import { Configuration, FrontendApi } from "@ory/client" diff --git a/docs/kratos/manage-identities/40_invite-users.mdx b/docs/kratos/manage-identities/40_invite-users.mdx index 48e874e586..5a7f66051e 100644 --- a/docs/kratos/manage-identities/40_invite-users.mdx +++ b/docs/kratos/manage-identities/40_invite-users.mdx @@ -97,3 +97,11 @@ more. "expires_at": "2023-02-18T02:16:47.286385565Z" } ``` + + :::tip + + When you develop locally with [Ory Tunnel](../../getting-started/local-development.mdx), replace the project slug domain in the + recovery link with your Ory Tunnel URL (for example `http://localhost:4000`). If you don't do this, clicking the link causes a + CORS error. Read [CSRF troubleshooting](../../troubleshooting/10_crsf.mdx#admin-api-urls-in-local-development) for more details. + + ::: diff --git a/docs/troubleshooting/10_crsf.mdx b/docs/troubleshooting/10_crsf.mdx index b4f2f5a192..fc7bbd3e5b 100644 --- a/docs/troubleshooting/10_crsf.mdx +++ b/docs/troubleshooting/10_crsf.mdx @@ -59,6 +59,21 @@ you need to configure your AJAX request to include cookies, because AJAX doesn't For example, when using the browser's `fetch` function, you need to set [`credentials: 'include'`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters). +### Admin API URLs in local development + +When you develop locally with [Ory Tunnel](../getting-started/local-development.mdx), Admin API endpoints such as +`/admin/recovery/link` and `/admin/recovery/code` return URLs that point to your project slug domain, for example +`https://{project-slug}.projects.oryapis.com/self-service/recovery?flow=...`. When a user opens one of these URLs in the browser, +the request goes to a different origin than your local application. This causes a CORS error that can surface as a +`401 Unauthorized` response or an unhandled error in the Ory SDK. + +To fix this, replace the project slug domain in the URL with your Ory Tunnel URL before you send the link to users. For example, +replace `https://{project-slug}.projects.oryapis.com` with `http://localhost:4000`. + +This applies to all flows that use Admin API-generated URLs in the browser, including the +[account recovery](../kratos/manage-identities/30_account-recovery.mdx) and +[invite users](../kratos/manage-identities/40_invite-users.mdx) flows. + ### Accessing APIs from a server-side application When building a server-side application, make sure to include the `Cookie` header from the client when fetching the self-service From 91653281a0e2c8ccd8bee375a1976451d8f574ea Mon Sep 17 00:00:00 2001 From: vinckr Date: Tue, 10 Feb 2026 11:03:09 -0300 Subject: [PATCH 2/2] chore: format --- docs/getting-started/local-development.mdx | 6 +++--- docs/kratos/manage-identities/40_invite-users.mdx | 3 ++- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/getting-started/local-development.mdx b/docs/getting-started/local-development.mdx index 5bdc943a40..ddf694d92a 100644 --- a/docs/getting-started/local-development.mdx +++ b/docs/getting-started/local-development.mdx @@ -104,9 +104,9 @@ available. The `--dev` flag disables a few security checks to make local develop performing the registration flow: [`http://localhost:4000/ui/registration`](http://localhost:4000/ui/registration). You can now start developing locally. Make sure to send any HTTP calls you make to `http://localhost:4000` and not -`https://{your-slug}.projects.oryapis.com`. This also applies to URLs returned by Admin API endpoints, such as recovery or -invite links. These URLs point to the project slug domain by default and must be rewritten to the Tunnel URL before use in the -browser. Read [CSRF troubleshooting](../troubleshooting/10_crsf.mdx#admin-api-urls-in-local-development) for more details. +`https://{your-slug}.projects.oryapis.com`. This also applies to URLs returned by Admin API endpoints, such as recovery or invite +links. These URLs point to the project slug domain by default and must be rewritten to the Tunnel URL before use in the browser. +Read [CSRF troubleshooting](../troubleshooting/10_crsf.mdx#admin-api-urls-in-local-development) for more details. For example, when you configure the Ory SDK (here in Node.js): diff --git a/docs/kratos/manage-identities/40_invite-users.mdx b/docs/kratos/manage-identities/40_invite-users.mdx index 5a7f66051e..fc3330ba94 100644 --- a/docs/kratos/manage-identities/40_invite-users.mdx +++ b/docs/kratos/manage-identities/40_invite-users.mdx @@ -102,6 +102,7 @@ more. When you develop locally with [Ory Tunnel](../../getting-started/local-development.mdx), replace the project slug domain in the recovery link with your Ory Tunnel URL (for example `http://localhost:4000`). If you don't do this, clicking the link causes a - CORS error. Read [CSRF troubleshooting](../../troubleshooting/10_crsf.mdx#admin-api-urls-in-local-development) for more details. + CORS error. Read [CSRF troubleshooting](../../troubleshooting/10_crsf.mdx#admin-api-urls-in-local-development) for more + details. :::