OAuth redirects

Use an inbox as an OAuth redirect URI and capture the authorization code.

During an OAuth authorization-code flow, the provider sends the person's browser back to a redirect URI with a code and the state you sent. When the agent and the browser aren't on the same machine, or the provider insists on a registered HTTPS URL, an inbox makes a good redirect URI.

When you need this#

The agent runs in the cloud, in a sandbox or in CI, and the person signs in from their own laptop or phone.
The provider only accepts HTTPS redirect URIs it can reach, so http://localhost isn't an option.
You want the agent itself to receive the code, not a local app.

If the agent and the browser are on the same machine and the provider allows loopback redirects (http://127.0.0.1:<port>/callback), a local listener works without Porch.

The flow#

1. Create an inbox with a short lifetime:

create_inbox

{ "ttl_minutes": 30 }

2. Register the redirect URI <url>/oauth/callback with the provider (in its developer console, or when the agent registers the client).

3. Optional: show a friendly page. By default the person sees a "Delivered" page. To show your own, set a response first:

set_response

{
  "inbox_key": "porch_sk_…",
  "path_prefix": "/oauth/callback",
  "body": "<h1>You're signed in</h1><p>You can close this tab and return to your agent.</p>"
}

Or send them somewhere with "status": 302 and "headers": { "Location": "https://example.com/done" }.

4. Send the person the authorize URL, including a random state the agent remembers:

https://provider.example/oauth/authorize?response_type=code&client_id=…&redirect_uri=<url>/oauth/callback&state=8f3c…&scope=…

5. Wait for the redirect:

wait_for_request

{ "inbox_key": "porch_sk_…", "path_prefix": "/oauth/callback", "timeout_seconds": 300 }

The code and state arrive parsed:

json

{ "request": { "method": "GET", "path": "/oauth/callback", "query": { "code": "4/0AbC…", "state": "8f3c…" } } }

6. Check state, then exchange the code yourself. Compare state with the value you generated, then call the provider's token endpoint from the agent. Use PKCE where the provider supports it.

Keep secrets out of Porch#

Porch only sees the redirect, which carries a short-lived code. Never send client secrets or tokens through an inbox, and delete the inbox once the code is exchanged:

delete_inbox

{ "inbox_key": "porch_sk_…" }

Errors from the provider#

If the person cancels or the provider rejects the request, the redirect carries error and error_description instead of code. Check query.error before looking for the code.