OAuth PKCE for External Apps

External apps can ask Hadrian users to grant them an API key without ever seeing the user's credentials, using the same PKCE flow popularised by OpenRouter's OAuth flow.

The user clicks a button in your app, lands on Hadrian's consent page, clicks Authorize, and is sent back to your app with a one-time code. Your app exchanges that code for an API key.

Standards

Hadrian implements the subset of OAuth 2.0 needed for the PKCE authorization-code flow. Specifically:

• RFC 7636 — Proof Key for Code Exchange — governs the code_verifier / code_challenge exchange. S256 is the default and recommended method; plain is gated behind auth.oauth_pkce.allow_plain_method.
• RFC 6749 §4.1 — Authorization Code Grant — the overall request/response shape. The token endpoint uses invalid_grant (RFC 6749 §5.2) when a code is unknown, expired, reused, or paired with the wrong verifier.
• RFC 8414 — Authorization Server Metadata — served at /.well-known/oauth-authorization-server so PKCE clients can discover the authorize/token endpoints, supported challenge methods, and supported scopes without hard-coding URLs.

What Hadrian does not implement (and clients shouldn't expect):

• Dynamic Client Registration (RFC 7591) — apps don't pre-register; the consent screen is the only gating step.
• Refresh tokens — the issued credential is a regular Hadrian API key with the rotation, expiry, and revoke semantics documented for self-service keys.
• Client credentials / password / device-code grants — only the PKCE authorization-code grant is supported.

Discovering the endpoints

GET https://hadrian.example.com/.well-known/oauth-authorization-server

returns:

{
  "issuer": "https://hadrian.example.com",
  "authorization_endpoint": "https://hadrian.example.com/oauth/authorize",
  "token_endpoint": "https://hadrian.example.com/oauth/token",
  "code_challenge_methods_supported": ["S256"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code"],
  "token_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": [
    "chat",
    "completions",
    "embeddings",
    "images",
    "audio",
    "files",
    "models",
    "admin"
  ],
  "service_documentation": "https://hadrian.example.com/docs/features/oauth-pkce"
}

The discovery document is unauthenticated by RFC 8414, so Hadrian deliberately does not consume X-Forwarded-* headers when building it — those are trivially spoofable and would let an attacker poison the document into advertising attacker-controlled endpoints. Operators behind a reverse proxy (or anywhere the externally-visible URL differs from the bind address) must set auth.oauth_pkce.public_url:

[auth.oauth_pkce]
public_url = "https://hadrian.example.com"

When public_url is unset, the document falls back to building URLs from server.host, server.port, and server.tls.

Flow

function base64url(bytes: Uint8Array) {
  return btoa(String.fromCharCode(...bytes))
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=+$/, "");
}

const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
const challengeBytes = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
const challenge = base64url(new Uint8Array(challengeBytes));

sessionStorage.setItem("hadrian-verifier", verifier);

https://hadrian.example.com/oauth/authorize?
  callback_url=https://yourapp.example/cb&
  code_challenge=<challenge>&
  code_challenge_method=S256&
  app_name=YourApp&
  scopes=chat,embeddings

const code = new URLSearchParams(location.search).get("code");
const verifier = sessionStorage.getItem("hadrian-verifier");

const response = await fetch("https://hadrian.example.com/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ code, code_verifier: verifier }),
});

const { key, key_prefix, key_id } = await response.json();

Server configuration

The flow is enabled by default. Tune it under [auth.oauth_pkce] in hadrian.toml:

[auth.oauth_pkce]
# Disable the flow entirely. Both /oauth/authorize and /oauth/token return
# 404 when this is false.
enabled = true

# Code lifetime in seconds (max 3600). Codes are also single-use.
code_ttl_seconds = 600

# Require S256 (recommended). Set true to also accept plain verifiers.
allow_plain_method = false

# Optional callback host allow/deny lists. Each entry matches the host
# exactly or as a parent domain (so "example.com" allows "app.example.com").
# Leave allowed_domains empty to allow any host. denied_domains always wins.
allowed_domains = []
denied_domains = []

# Externally-visible base URL of this deployment, used as the issuer in
# /.well-known/oauth-authorization-server. Required when Hadrian is reached
# via a different host than `server.host:server.port` (e.g. behind a reverse
# proxy). Forwarded headers are NOT trusted on the unauthenticated discovery
# endpoint, so this must be set explicitly.
# public_url = "https://hadrian.example.com"

Restricting which apps can use the flow

For most installations the default — open allowlist, no denylist — is fine: the user must explicitly approve every app on a Hadrian-hosted page, and any key issued is bound to their account.

If you need stricter controls, populate allowed_domains:

[auth.oauth_pkce]
allowed_domains = ["yourcompany.dev", "trusted-partner.io"]

To disable the flow for a single deployment without changing TOML across the fleet, set HADRIAN_AUTH__OAUTH_PKCE__ENABLED=false in the environment.

Security notes

• The PKCE verifier is the only secret in the flow. Generate it with a CSPRNG and never log it.
• code_challenge_method = plain is disabled by default. Don't enable it unless you have a hard reason to support a client that can't compute SHA-256.
• The redirect URL is validated server-side: HTTPS is required (HTTP is permitted only for localhost/127.0.0.1/::1). Allow/deny lists are applied to the host before any code is issued.
• Authorization codes are single-use, expire (default 10 minutes), and are bound to the original PKCE challenge. A code that is replayed or used with the wrong verifier returns 400 invalid_grant.
• Every issued code is recorded in the audit log under api_key.oauth_authorize, with the callback host and the requesting user.