Skip to content

fix: admin API URLs in local dev #2439

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vinckr merged 2 commits into from
Feb 10, 2026
Merged

fix: admin API URLs in local dev #2439

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
75219df
fix: admin API URLs in local dev
vinckr Feb 10, 2026
9165328
chore: format
vinckr Feb 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion docs/getting-started/local-development.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
9 changes: 9 additions & 0 deletions docs/kratos/manage-identities/40_invite-users.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

:::
15 changes: 15 additions & 0 deletions docs/troubleshooting/10_crsf.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading