diff --git a/docs/getting-started/local-development.mdx b/docs/getting-started/local-development.mdx index 4db710f86c..ddf694d92a 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..fc3330ba94 100644 --- a/docs/kratos/manage-identities/40_invite-users.mdx +++ b/docs/kratos/manage-identities/40_invite-users.mdx @@ -97,3 +97,12 @@ 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