integration-proxy
A Rust web server that holds OAuth grants and pasted API keys for third-party platforms, and forwards catalog-allowlisted requests to them on behalf of Atomic agents.
There are no proxy accounts, logins or tenants (issue
#54). The account is
the caller's Atomic agent, atomic:agent:<public key>: every request that
matters is signed with that key, and the proxy verifies it against the key
inside the id, so it looks nothing up. A connection (one provider grant)
is owned by the agent that redeemed it; the owner delegates it to app
agents, and may register runtimes (a node's app agent) for them. A plugin
frame, which cannot keep a key, uses a short-lived capability signed by
the owner and bound to a key the frame holds in memory.
PostgreSQL stores connections (provider credentials sealed with XChaCha20-Poly1305), delegations, runtimes, five-minute connect handoffs and the single-use record of signed requests.
Built with axum, following the OAuth 2.0 Authorization Code flow with PKCE towards providers.
To run your own instance, see SELF_HOSTING.md:
installing (cargo install, Docker, systemd), configuration, PostgreSQL TLS,
a reverse proxy, registering OAuth apps, pointing Atomic Server and the data
browser at it, upgrades, backups and health checks. This README describes
the protocol and the code.
How it works
Identity
Agent ids are accepted as atomic:agent:<key> or the legacy
did:ad:agent:<key>, with <key> in either base64 alphabet, padded or not.
They are converted to one canonical form, atomic:agent: plus the unpadded
base64url key, before they are stored or compared, and only that form is
ever returned. Only Ed25519 keys exist today; one function
(agent_id::parse) is where another algorithm would be added.
Request signatures (Atomic v2)
Every signed request carries Atomic's own headers:
| Header | Value |
|---|---|
x-atomic-agent |
the signer's agent id |
x-atomic-public-key |
the signer's Ed25519 public key, base64 |
x-atomic-timestamp |
Unix milliseconds |
x-atomic-signature |
base64 Ed25519 signature over the message below |
x-atomic-signature-version |
2 |
The signed message is five lines joined by \n, with no trailing newline:
atomic-request-v2
{METHOD}
{full URL, including query}
{timestamp, exactly as in x-atomic-timestamp}
{lowercase hex SHA-256 of the body; e3b0c442…b855 when empty}
The proxy accepts version 2 only; a missing or different version header is
refused, never retried as v1. The agent must be atomic:agent: of the public
key header. The timestamp must be within ±5 minutes of the proxy's clock, and
each signed message is accepted once (a SHA-256 of it is kept for ten
minutes).
Full URL is BASE_URL followed by the request's path and query exactly as
received, e.g. https://localthought.io/proxy/<id>/github-issues/user/repos?page=2.
It is never rebuilt from the Host header: behind a TLS-terminating reverse
proxy or platform router the process sees plain HTTP. Clients sign the URL they fetch (new URL(u).href).
BASE_URL must therefore be exactly the public origin clients use.
Routes
GET /— a static landing page.GET /cataloglists the platforms;GET /catalog/{platform}.yamlreturns a platform's composed OpenAPI document.GET /connect?platform=<p>&redirect_uri=<url>&code_challenge=<S256>&code_challenge_method=S256— the consent page, naming the platform and the destination. No login.redirect_urimust behttps, loopbackhttp, or the Atomic app's deep link (atomic://…); it may not carryconnection_codeorerrorparameters, credentials or a fragment.POST /connect/authorize— the consent form (cookie-bound CSRF token, single use). For an OAuth platform it answers200with a page that continues to the provider (a<meta>refresh plus a button, sent withReferrer-Policy: no-referrer) rather than redirecting: the consent page's CSPform-actiongoverns a form submission's whole redirect chain, and a provider whose authorization endpoint first redirects to another origin of its own (Notion's API host to its app host, for one) would be blocked. The consent page therefore allows form submissions to the proxy only. 0.2.2 and later; 0.2.1 redirected (303). For an API-key platform (type: apiKeyin the composed document) the consent page asks for the key, and this seals it and redirects (303) toredirect_uri. When the scheme declaresx-api-key-details(openapi-extensions/spec/api-key-details, 0.2.3 and later), the page shows the scheme'sdescriptionand links itshelpUrl(a plain link that opens in a new tab), and this first calls the declaredkeyCheckoperation once with the key: a fixedGETon the document's ownhttpsserver, no redirects, 10-second timeout. A401or403answers the consent page again (200) saying the key was not accepted, without spending the consent; any other non-2xx, a redirect or no answer is a400and nothing is stored. A 2xx may give a label (at most 200 characters, sealed with the connection). For a platform whose composed document declares top-levelsecurity: []and no security scheme (0.2.3 and later), the consent page asks for nothing, and this hands off a connection that holds no credential and redirects (303) toredirect_uri; requests are forwarded with none. Approving the same consent page twice answers400"You already approved this connection …" rather than "expired"; the page's one inline script (allowed by its hash) disables the button after the first click.GET /oauth/{platform}/callback— the provider's callback. Only the browser that approved consent can complete it. It redirects toredirect_uri?connection_code=<handoff>(or?error=access_denied). The handoff is not a credential: it is single-use, valid five minutes, and bound to the PKCE challenge.POST /connect/redeem— signed; body{"code": "<handoff>", "code_verifier": "<PKCE verifier>"}; answers{"connection_id", "platform", "owner", "label"?}. The signer becomes the owner.labelis there when an API-key platform's key check gave one. A wrong verifier does not burn the handoff.ANY /proxy/{connection_id}/{platform}/{path}— signed by the owner, a delegated app agent, or a registered runtime of a delegated app; or carrying a frame capability (below). The proxy attaches the provider credential, refreshing an expiring OAuth token (one refresh in flight per connection), and forwards only catalog-allowlisted methods and paths. The caller'sAuthorizationandx-atomic-*headers are never forwarded.Link,Retry-After,ETag,X-Total-CountandX-Next-Pagecome back unchanged.GET /connections— signed; the signer's connections with their delegations (agent,label,created_at,last_used_at), and the signer's runtimes. Never credentials. Shape:{"owner", "connections": [{"connection_id", "platform", "owner", "label"?, "created_at", "last_used_at", "delegations": [...]}], "runtimes": [{"agent", "app", "label", "created_at", "last_used_at"}]}. A connection'slabelis the key check's label (see/connect/authorize), absent otherwise.DELETE /connections/{id}— signed by the owner; deletes the connection and its delegations.204.POST /connections/{id}/agents— signed by the owner; body{"agent", "label"?}delegates the connection to that app agent.DELETE /connections/{id}/agents/{agent}removes the delegation.204.POST /runtimes— signed; body{"app", "agent", "label"?}registersagent(a node's app agent) as a runtime of installationappfor the signer.DELETE /runtimes/{agent}removes it. A runtime can use every connection its app is delegated.GET /healthz—200 okwhen the database answers.
Delegations and runtimes are read on every proxied request, so removing one
takes effect on the next request. A connection is deleted after 90 days
without an authenticated request (CONNECTION_IDLE_DAYS).
Frame capabilities
A plugin frame (null origin, no storage) generates a non-extractable key in memory; its page, which holds the user's key, signs a capability for it:
Authorization: Capability <payload>.<sig>
payload = base64url(JSON), unpadded:
{"v":2,"connection_id","platform","aud","app","cnf","exp"}
sig = the connection owner's Ed25519 signature, base64, over
"integration-proxy-capability-v2\n" + the JSON bytes
aud is the proxy origin (BASE_URL's scheme, host and port); app is the
installation's app agent, which must hold a delegation; cnf is the frame's
key as atomic:agent:<key>; exp is Unix seconds, at most 15 minutes ahead.
The request itself must also carry v2 headers signed by cnf's key, so a
copied capability is useless without the frame. The proxy checks, in order:
the owner's signature, aud, exp, connection_id and platform, the
delegation for app, and the request signature by cnf (with skew and
replay). On 401 capability_expired the frame asks its page for a new one.
Errors
Signed endpoints answer errors as JSON, {"error": "<code>", "message": "<text>"}:
| Status | error |
|---|---|
| 401 | missing_signature, unsupported_signature_version, invalid_agent, agent_key_mismatch, stale_timestamp, bad_signature, replayed, unsupported_authorization (e.g. a retired Bearer connection code), invalid_capability, capability_expired, capability_too_long, wrong_audience, capability_key_mismatch, credential_refresh_failed (connect again) |
| 403 | not_owner, not_delegated, capability_scope, platform_mismatch, access_denied |
| 404 | unknown_connection (deleted, idle-expired, or never existed: connect again) |
| 400 | bad_request, invalid_handoff |
Catalog refusals and upstream failures from /proxy/… keep their plain-text
bodies (404 method or path is not in the catalog, 502 upstream request failed).
Who may use the proxy
Every signed request's connection owner (and the redeemer, at
/connect/redeem) is checked against an AccessPolicy. Delegated agents and
frames are checked as their owner, so limits count per owner. The default
policy admits every agent except those in REVOKED_SUBJECTS, and only those
in ALLOWED_AGENTS when that is set. The atomic.place deployment is meant to
plug in a lookup of the agent's SaaS account and tier
(build_app_with_access); how an agent is linked to an
account is decided in ontola/atomic-saas#138 and is not implemented here.
What was removed (flag day)
Issue #54 decision 6 switched these off with no migration: OIDC application
login (/auth/login, /auth/callback, /auth/logout, APP_AUTH_*), API
identity login (/auth/login/{platform}, catalog tenantIdentity),
tenant:v1: tenants, tenant secrets and SERVER_SECRET, /session, the
legacy signed /connect and /oauth/{platform}/start, the /proxy
tenant-secret check, the user_id and credentials parameters of
/connect, and rotating connection codes (Authorization: Bearer and
X-Connection-Code). Existing connection codes stop working; users connect
again. The old connection_codes and oauth_states tables are no longer
read or written but are not dropped automatically; once the new version is
deployed, an operator may drop them with
DROP TABLE IF EXISTS connection_codes, oauth_states;.
Setup
1. Configure environment variables
Nothing in the process reads .env files; export the variables, or load a
.env into your shell first (set -a; source .env; set +a).
| Variable | Required | Description |
|---|---|---|
BASE_URL |
no | Public URL of the proxy, e.g. https://localthought.io. Defaults to http://localhost:8080. Used for OAuth callback URLs, as the prefix of every signed URL, and (its origin) as a capability's aud. Must be exactly what clients use. |
PORT |
no | Port to listen on. Defaults to 8080. |
SESSION_SECRET |
no; set it in production | Secret for the short-lived consent and OAuth-binding cookies. If unset, a random key is generated at startup (with a warning in the log), and a consent screen open during a restart must be started again. Instances behind one name must share it. |
CATALOG_PATH |
no | Local path or HTTPS URL for the catalog JSON. Defaults to https://ontola.github.io/atomic-plugins/overlays/catalog/2026-10-02.json, this repository's overlays/catalog/2026-10-02.json as GitHub Pages publishes it from main. |
DATABASE_URL |
yes | PostgreSQL connection URL. See the TLS note below. |
ENCRYPTION_KEY |
yes | Base64url-encoded, random 32-byte key for sealed provider credentials. Changing it makes every stored connection unreadable. |
REVOKED_SUBJECTS |
no | Comma-separated agent ids (any accepted spelling) the default access policy refuses. |
ALLOWED_AGENTS |
no | When set, comma-separated agent ids; the default access policy admits only these owners. |
OPERATOR_NAME |
no | Who runs this proxy, as the landing and consent pages name them. Defaults to this integration proxy, and the pages then name no one. The consent page also shows the host of BASE_URL. 0.2.1 and later. |
OPERATOR_URL |
no | Absolute http(s) link for OPERATOR_NAME on those pages. Anything else (javascript:, a relative path, credentials in the URL) is refused at startup. 0.2.1 and later. |
OAUTH_<PLATFORM>_CLIENT_ID, OAUTH_<PLATFORM>_CLIENT_SECRET, OAUTH_<PLATFORM>_CLIENT_AUTH_METHOD |
per OAuth platform | See below. |
OAuth credentials are provider-specific. For a catalog platform named
google-calendar, configure OAUTH_GOOGLE_CALENDAR_CLIENT_ID and
OAUTH_GOOGLE_CALENDAR_CLIENT_SECRET; its callback URI is
<BASE_URL>/oauth/google-calendar/callback. Provider names use lowercase
letters, digits, and hyphens, and are converted to uppercase with hyphens
replaced by underscores for environment-variable names.
The server owns the OAuth endpoints and scopes for every platform in the catalog, reading them from that platform's composed OpenAPI document; a request cannot supply a provider URL, token URL, or scope.
The PostgreSQL client validates the database's TLS certificate against the
system roots when TLS is used; sslmode in DATABASE_URL decides whether it
is (prefer by default, which falls back to plaintext against a server
without TLS). Use ?sslmode=disable for a PostgreSQL on the same host and
?sslmode=require across any network; see
SELF_HOSTING.md. A managed
PostgreSQL may set DATABASE_URL for you (Heroku's Postgres add-on does).
Schema setup runs in a transaction under an advisory lock, so several
instances can start against an empty database at once.
Catalog
Per-platform OAuth app registration for any deployment is in
SELF_HOSTING.md. Every callback is
<BASE_URL>/oauth/<platform>/callback; the examples below use the
localthought.io deployment's BASE_URL.
Discord uses OAUTH_DISCORD_CLIENT_ID and OAUTH_DISCORD_CLIENT_SECRET,
with callback https://localthought.io/oauth/discord/callback on localthought.io.
Register an OAuth application in the Discord Developer Portal. The initial
read-only integration uses identify and guilds to read your profile and
import server memberships; it does not import messages or require a bot token.
The guild import requests limit=200, covering Discord's documented maximum
number of guilds for a user. The profile endpoint is available as a read
operation, not an imported collection.
Discord access tokens expire and use the existing refresh-token flow.
Spotify uses OAUTH_SPOTIFY_CLIENT_ID and the callback
<BASE_URL>/oauth/spotify/callback (on localthought.io,
https://localthought.io/oauth/spotify/callback). Register a
Spotify Web API app with that exact redirect URI. The integration uses
Authorization Code with PKCE, so no client secret is required or transmitted;
the catalog declares only none, so the proxy neither requires nor sends
one (OAUTH_SPOTIFY_CLIENT_AUTH_METHOD=none is equivalent). It imports playlists with playlist-read-private and
playlist-read-collaborative; no write scopes are requested. No account ID
parameter is needed. Development-mode access is subject to Spotify's Premium
and app-user allowlist requirements. Access tokens refresh automatically;
expired or revoked refresh tokens require reconnecting through OAuth.
Moneybird uses OAUTH_MONEYBIRD_CLIENT_ID and
OAUTH_MONEYBIRD_CLIENT_SECRET, with callback
<BASE_URL>/oauth/moneybird/callback. Register an
external OAuth application, rather than a personal API token. The
sales_invoices scope grants access to contacts (Moneybird has no contacts-only
scope). The initial integration imports contacts; supply the administration ID
from the Moneybird account when connecting. OAuth tokens without expires_in
remain usable until revoked; tokens with an expiry use the normal refresh flow.
overlays/catalog/2026-10-02.json in this repository
(migrated from the former localthought/overlays repository) is the source of
the integration catalog. GitHub Pages publishes overlays/ from main at
https://ontola.github.io/atomic-plugins/overlays/, and the proxy defaults to
the catalog/2026-10-02.json there; set CATALOG_PATH to another HTTPS URL or to a
local fixture for development. Each platform names one pinned OpenAPI document
(in localthought/ or ontola/openapi-directory, at a commit) and zero or more Overlay
Specification documents, each served from that same Pages folder. At startup
the proxy downloads those HTTPS sources, applies each overlay's update
actions in the listed order, and keeps the resulting YAML in memory.
Provider overlay filenames include their kind and full OAD commit SHA under
overlays/APIs/, so adding a newer OAD revision leaves existing catalog
selections intact. Each overlay's extends identifies that same pinned OAD.
The loader rejects a mismatched declaration before applying actions, resolves
relative extends against the overlay URL, and continues to support older
overlays that omit it. Published revision files are immutable; updating a
platform means explicitly changing its openapi and ordered overlays
selections together.
A catalog entry may also contain a selection object. Consumer query_overrides remain separate from the composed OpenAPI document: choosing to include archived records is client configuration, not an API default. The proxy passes those choices through. selection.oauthSecurityScheme is trusted server configuration: when a document contains multiple OAuth authorization-code Security Schemes, it names the one the proxy uses. The value must be a string naming a declared scheme. GET /catalog/{platform}.selection.json returns the selection object (or an empty object when absent).
Overlay URLs use immutable OAD-revision filenames. Publish new overlay
filenames and a new dated catalog together, then explicitly switch
CATALOG_PATH or the proxy default to that dated catalog; Overlays CI and
this crate's default_catalog_* tests (which compose the checked-in catalog,
reading the Pages-published overlays from ../overlays/) validate it before
merge; after merge, Overlays published checks that Pages serves the merged
bytes; then restart the service. OAD URLs remain pinned to an
openapi-directory commit. Overlay content cannot currently be pinned: a
CATALOG_PATH pointing at a local file or at a commit's
raw.githubusercontent.com copy of catalog.json still lists Pages URLs, so
its overlays are whatever main serves when the proxy starts.
2. Run it
Then open http://localhost:8080 (or your configured BASE_URL). For a
deployment, see SELF_HOSTING.md; GET /healthz is the
health check.
Development
CI runs the same checks on every push and pull request that touches
integration-proxy/ (see the repository's
.github/workflows/integration-proxy-ci.yml), plus cargo package --locked
and a build of the Heroku wrapper template.
Library crate
This package is published to crates.io as
atomic-integration-proxy
(library atomic_integration_proxy, binary integration-proxy), so a
deployment can be a thin wrapper that depends on it by semver instead of a
copy of the source. The public API is intentionally small; everything else is
private and may change in any release:
| Item | What it does |
|---|---|
Config, Config::from_env() |
All configuration, read from the environment variables described above. |
DEFAULT_CATALOG_PATH |
The pinned catalog URL used when CATALOG_PATH is unset. |
build_app(&Config) -> Result<axum::Router, Error> |
Loads the catalog, connects to PostgreSQL, returns the router (CORS and tracing layers included), with the default EnvAccessPolicy. |
build_app_with_access(&Config, Arc<dyn AccessPolicy>) |
The same, admitting connection owners through a custom policy (e.g. a SaaS account and tier lookup). |
AccessPolicy, Access, AllowAll, EnvAccessPolicy |
The admission check asked about every owner; AllowAll for a self-hosted proxy. |
AgentId, parse_agent_id |
A parsed agent id; as_str() is the canonical atomic:agent: form. |
serve(Config) -> Result<(), Error> |
build_app, then bind 0.0.0.0:{PORT} and serve. |
run() -> ExitCode |
What the binary does: init tracing from RUST_LOG (default info), Config::from_env, serve, print any Error to stderr. |
Error |
Startup/serve failure; Display is the one-line message the binary prints. |
A complete wrapper main.rs is:
async
The only runtime file access is CATALOG_PATH when it is set to a local
path; the default is a pinned HTTPS URL, and static/ is compiled into the
binary, so the crate needs no files next to the executable.
Publishing the crate
.github/workflows/integration-proxy-publish.yml publishes when a tag
integration-proxy-v<version> matching Cargo.toml's version is pushed.
It reruns fmt, clippy and the full test suite (including the PostgreSQL tests)
first, then publishes through crates.io Trusted Publishing. crates.io only
allows Trusted Publishing to be configured on a crate that already exists, so
0.1.0 must be published once by hand by whoever will own the crate; the
workflow header lists the one-time crates.io settings. To release:
# bump `version` in integration-proxy/Cargo.toml, merge, then on main:
&&
&&
Only src/, static/index.html, static/logo.png, Cargo.toml,
Cargo.lock, README.md, CHANGELOG.md, SECURITY.md and LICENSE are packaged
(cargo package --list shows the exact list). tests/ fixtures are not, so
cargo test only works from a checkout of this repository.
The localthought.io deployment (Heroku)
This section is about one deployment, not a requirement: the crate runs on
any host that provides the environment variables, one HTTP port and
PostgreSQL (SELF_HOSTING.md). localthought.io runs on
Heroku from the separate repository
localthought/integration-proxy, which since its PRs #77 (wrapper) and #78
(0.2.1 from crates.io) holds only the examples/heroku-wrapper/ files
and depends on atomic-integration-proxy from crates.io. A change merged here
reaches production only after it is published (see "Publishing the crate")
and that repository's Cargo.lock is bumped:
# in a localthought/integration-proxy checkout, once <version> is on crates.io
# (raise the requirement in Cargo.toml too when the deployment needs it)
Merging that to its main deploys. Do not copy this source tree there: the
wrapper is the whole repository now.
From 0.2.1 the landing and consent pages no longer say "LocalThought"
unless told to: set OPERATOR_NAME=LocalThought and
OPERATOR_URL=https://localthought.io (Heroku config vars) to keep naming
it, or leave both unset for the neutral "this integration proxy".
Deploying 0.2 (issue #54 flag day)
0.2 changes the client protocol; deploy it together with the atomic-server
release that signs requests (Atomic v2) and uses /proxy/{connection_id}/…,
never before it. Environment (on Heroku, config vars):
| Variable | Change |
|---|---|
BASE_URL |
Check: must be exactly the public origin clients use (for production https://localthought.io, no trailing path). Every signature covers it; a mismatch makes every signed request fail with bad_signature. |
APP_AUTH_CLIENT_ID, APP_AUTH_CLIENT_SECRET, APP_AUTH_AUTHORIZATION_URL, APP_AUTH_TOKEN_URL, APP_AUTH_USERINFO_URL, APP_AUTH_LABEL, APP_AUTH_IDENTITY_NAMESPACE |
No longer read; unset them (on Heroku, heroku config:unset …). 0.1 refused to start without the first five; 0.2 ignores them. |
SERVER_SECRET |
No longer read; unset it. |
REVOKED_SUBJECTS |
Now means agent ids; tenant ids and OIDC subjects listed there no longer match anything. Rewrite or unset it. |
ALLOWED_AGENTS |
New, optional: restrict the proxy to these owners. |
SESSION_SECRET, DATABASE_URL, ENCRYPTION_KEY, CATALOG_PATH, PORT, OAUTH_* |
Unchanged. |
Existing connection codes stop working at deploy; users connect again. After
the deploy, DROP TABLE IF EXISTS connection_codes, oauth_states; removes the
old sealed credentials (optional, irreversible).
Security
Provider credentials are sealed per connection row (the associated data binds each envelope to its row) and never returned to a client. Requests go only to catalog-allowlisted methods and paths. SECURITY.md describes the controls and what is not yet verified.
Notes on state
- Nothing identifies a browser session: there are no session cookies. The
consent screen and the OAuth callback use two short-lived (10 minute)
encrypted
Secure/HttpOnly/SameSite=Laxcookies:platform_consent(the pending request and CSRF token) andplatform_oauth(binding the callback to the approving browser). Provider state, handoffs and connections live in PostgreSQL, so any instance can serve any request. - Cookies are marked
Secure, so in productionBASE_URLmust usehttps://.http://localhostworks during local development because browsers treatlocalhostas a secure context.
Browser clients
CORS allows any origin, including a plugin frame's null origin, to send
Authorization, Content-Type, If-Match and the five x-atomic-* headers,
and exposes Content-Type, Link, Retry-After, ETag, X-Total-Count and
X-Next-Page. Cookie credentials are not enabled for CORS; consent remains a
top-level browser navigation.
Todoist
The todoist platform imports projects and active tasks through Todoist API v1
with the read-only data:read scope. Configure OAUTH_TODOIST_CLIENT_ID and
OAUTH_TODOIST_CLIENT_SECRET, and register
<BASE_URL>/oauth/todoist/callback as the OAuth redirect URL.
New Todoist applications issue expiring access tokens and rotating refresh
tokens; the proxy stores and refreshes these through its existing credential flow.
Legacy non-expiring access tokens are also supported. No provider writes are exposed.
Provider documentation: https://developer.todoist.com/api/v1/
Redirect-flow regression checks
# Isolated local PostgreSQL, never a production database:
TEST_DATABASE_URL='postgres://postgres@localhost:15439/connect_test?sslmode=disable' \
OAUTH_GITHUB_ISSUES_CLIENT_ID=fixture-client OAUTH_GITHUB_ISSUES_CLIENT_SECRET=fixture-secret \
CI provides PostgreSQL and includes the database tests; TESTING_COVERAGE.md maps each verification step to its tests. Live Google/GitHub authorization and a hub import must be verified against matching deployed revisions of the proxy and atomic-server; local fixture checks do not establish live access.
OAuth client registration
Integration authorization and token endpoints and required scopes are read from the composed OpenAPI catalog. A platform with one OAuth authorization-code Security Scheme uses it directly. A platform with multiple such schemes must set the catalog's trusted selection.oauthSecurityScheme; missing, non-string, or unknown selections fail closed. Requests cannot select a scheme or supply endpoints. Scopes are taken from operation security requirements (falling back to root requirements), not every scope supported by the server. Public operations require no scopes; unsupported authentication combinations fail closed.
OAUTH_<PLATFORM>_CLIENT_AUTH_METHOD optionally overrides the client authentication method: none, client_secret_post, or client_secret_basic. When omitted, the proxy selects the first usable method in the declared array order of x-oauth-authentication-details.authorizationServerMetadata.token_endpoint_auth_methods_supported in the selected OAuth security scheme. It skips methods the proxy does not implement and methods incompatible with the referenced token/refresh operations. If the array declares no usable method, configuration fails rather than silently falling back.
When that metadata is absent, the proxy retains client_secret_post for compatibility, except when a referenced token or refresh operation requires HTTP Basic authentication: it then uses client_secret_basic. Explicit overrides must still be supported by the metadata and token operations; an invalid override is an error, not a request to auto-select.
For example, Notion advertises only client_secret_basic, so its _CLIENT_AUTH_METHOD setting can be omitted. For ["private_key_jwt", "none", "client_secret_basic"], the proxy skips the unimplemented JWT method and chooses none. Array order is this proxy's default-selection policy, not an assertion of provider preference or the client's registered method. Set the override when your client registration requires a different advertised method. Public clients use none and do not load or send a secret; confidential methods require _CLIENT_SECRET. Missing credentials cause an error and do not trigger selection of another method. Authorization uses S256 PKCE unless trusted metadata explicitly declares PKCE unsupported.
The proxy implements a bounded subset of x-oauth-authentication-details. It reads inline token_endpoint_auth_methods_supported, code_challenge_methods_supported, PKCE requirements, and fixed authorization profile parameters. Parameter references must be local. Schema validation supports type, enum, recursive items, properties, required, and additionalProperties; other validation keywords fail closed. Serialization supports scalar form values, form/space/pipe-delimited scalar arrays, and form/deep-object scalar objects. Reserved OAuth fields and query-name collisions are rejected.
The proxy does not fetch oauth2MetadataUrl and does not interpret tokenEndpointOperation or refreshEndpointOperation. A selected scheme that contains any of those fields is rejected, because discovery or a separately described operation could require different token-request authentication or wire behavior.
Upgrading from 0.1 is a flag day (issue #54, decision 6): see
What was removed. Provider callback URLs and
OAUTH_* variables do not change; APP_AUTH_* and SERVER_SECRET are no
longer read and can be unset. Clients must move to signed requests at the
same time.