From fa223ee04ee7c256363c65db99837cd22e678474 Mon Sep 17 00:00:00 2001 From: Arne Luenser Date: Wed, 17 Jun 2026 10:51:44 +0200 Subject: [PATCH] feat: document expiring API key from ory tunnel --- docs/getting-started/local-development.mdx | 4 +++ docs/guides/cli/20_proxy-and-tunnel.mdx | 38 ++++++++++++++++++++++ 2 files changed, 42 insertions(+) diff --git a/docs/getting-started/local-development.mdx b/docs/getting-started/local-development.mdx index bc328bc838..9a7b15d599 100644 --- a/docs/getting-started/local-development.mdx +++ b/docs/getting-started/local-development.mdx @@ -103,6 +103,10 @@ Running this commands opens the `4000` port on your local machine. The URL `http available. The `--dev` flag disables a few security checks to make local development easier. After starting the Tunnel, test it by performing the registration flow: [`http://localhost:4000/ui/registration`](http://localhost:4000/ui/registration). +To configure your project so that flows such as Social Sign-In work, the Tunnel creates a short-lived API key for your project +while it runs and deletes it again on shutdown. See [Temporary API key](../guides/cli/20_proxy-and-tunnel.mdx#temporary-api-key) +for details, including how to control its expiry with `--api-key-expiry`. + 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. diff --git a/docs/guides/cli/20_proxy-and-tunnel.mdx b/docs/guides/cli/20_proxy-and-tunnel.mdx index af3b66f04d..4beba0a9f3 100644 --- a/docs/guides/cli/20_proxy-and-tunnel.mdx +++ b/docs/guides/cli/20_proxy-and-tunnel.mdx @@ -61,6 +61,44 @@ If you want to adjust the entry point URL, pass the desired address along with t ory tunnel --project --workspace http://localhost:3000 http://localhost:3001 ``` +## Temporary API key + +To configure your project for local development — for example to make complex flows such as Social Sign-In work — the Ory CLI +needs API access to your project while the Tunnel (or the deprecated Proxy) is running. To get it, the CLI creates a **temporary +project API key** on your behalf when the command starts, and removes it again when the command stops. + +:::note + +If you supply your own key through the `ORY_PROJECT_API_KEY` environment variable (as you typically would in automated +environments), the CLI uses that key directly and does **not** create or delete a temporary one. + +::: + +### Cleaning up on shutdown + +Deleting the key when the command stops is best-effort. If the process is terminated before it can clean up — for example it is +force-killed, the terminal is closed, or the machine loses power — the key is left behind and would otherwise remain valid +indefinitely. + +To prevent abandoned keys from accumulating, the CLI also gives the key a server-side **expiry**. Even if the local cleanup never +runs, Ory Network removes the key automatically once it expires. + +Use the `--api-key-expiry` flag to control how long the temporary key lives. It accepts a Go duration (such as `30m`, `12h`, or +`2h30m`) and defaults to `12h`. Set it to `0` to create the key without an expiry and rely solely on cleanup at shutdown: + +```shell +# Default: the temporary key expires 12 hours after the Tunnel starts. +ory tunnel --project http://localhost:3000 + +# Keep the key valid for longer before it expires. +ory tunnel --project --api-key-expiry 48h http://localhost:3000 + +# Disable the expiry entirely. +ory tunnel --project --api-key-expiry 0 http://localhost:3000 +``` + +The same `--api-key-expiry` flag is available on `ory proxy`. + ## Migration from Proxy to Tunnel Ory Proxy has been deprecated in favor of Ory Tunnel. This section guides you through migrating from Proxy to Tunnel.