tkhq · t-vila · Apr 10, 2026 · Apr 10, 2026 · Apr 10, 2026
diff --git a/Makefile b/Makefile
@@ -11,10 +11,18 @@ dev:
 install:
 	cd scripts/openapi-gen && npm install
 
-# Default MDX generation target
+# Generate MDX for all APIs (main + auth proxy).
+# Requires both swagger files to be present in the repo root — see README for copy commands.
 gen: mintlify-check
 	npx ts-node scripts/openapi-gen/swagger-to-openapi.ts
 	cd scripts/openapi-gen && npx ts-node openapi-gen.ts --file=openapi.json --generate-mdx
+	npx ts-node scripts/openapi-gen/swagger-to-openapi.ts --service=auth-proxy
+	cd scripts/openapi-gen && npx ts-node openapi-gen.ts \
+		--file=proxy_api_openapi.json \
+		--generate-mdx \
+		--mdx-output-dir=api-reference/auth-proxy \
+		--nav-group="Auth Proxy" \
+		--auth-proxy
 
 # Run the OpenAPI generator (allows custom ARGS)
 openapi-gen: mintlify-check

diff --git a/README.md b/README.md
@@ -48,7 +48,7 @@ We provide the following Make targets to generate API reference content:
 
 - `make install`: Install dependencies needed to run OpenAPI commands
 - `make openapi-gen`: Run the OpenAPI generator CLI with custom arguments. See [scripts/openapi-gen/README.md](scripts/openapi-gen/README.md) for details.
-- `make gen`: Default MDX generation for API reference under `api-reference/`.
+- `make gen`: MDX generation for all API references (main API + Auth Proxy) under `api-reference/`.
 - `make tags`: Generate the endpoint-tags MDX snippet at `snippets/data/endpoint-tags.mdx`.
 - `make mintlify-check`: This attempts to compare the locally installed version of mintlify cli against the latest published version on NPM. If the local version is behind this will attempt to update the version to the latest. This command gets run before `make gen`, `make openapi-gen`, and `make tags` to prevent parsing errors.
 
@@ -58,7 +58,7 @@ These commands require Node.js and `ts-node`.
 
 ### Mono Releases & Updating API Reference
 
-1. Checkout the specific [Mono Release tag](https://github.com/tkhq/mono/tags) and copy over [public_api.swagger.json](https://github.com/tkhq/mono/blob/main/src/js/internal/http/src/__internal__/services/coordinator/public/v1/public_api.swagger.json) to docs
+1. Checkout the specific [Mono Release tag](https://github.com/tkhq/mono/tags) and copy both swagger files `public_api.swagger.json` and `proxy_api.swagger.json` into the docs
    - `git checkout {latest_release_tag}` i.e. `v2025.12.1`
    - `make -C proto sync/docs`
 2. Run `make gen`

diff --git a/api-reference/auth-proxy/account.mdx b/api-reference/auth-proxy/account.mdx
@@ -0,0 +1,78 @@
+---
+title: "Get Account"
+description: "Return organization id associated with a given phone number, email, public key, credential ID or OIDC token."
+---
+
+import { H3Bordered } from "/snippets/h3-bordered.mdx";
+import { NestedParam } from "/snippets/nested-param.mdx";
+
+<div class="flex w-full flex-col bg-background-light dark:bg-background-dark border-standard rounded-2xl p-1.5 mb-4">
+  <div class="flex items-center space-x-1.5">
+    <div class="relative flex-1 flex gap-2 min-w-0 rounded-xl items-center cursor-pointer p-1.5 border-standard">
+      <div class="rounded-lg font-bold px-1.5 py-0.5 text-sm leading-5 bg-blue-400/20 dark:bg-blue-400/20 text-blue-700 dark:text-blue-400">POST</div>
+      <div class="text-sm font-mono text-gray-800 dark:text-white">https://authproxy.turnkey.com/v1/account</div>
+    </div>
+  </div>
+</div>
+
+<H3Bordered text="Authorizations" />
+
+<ParamField header="X-Auth-Proxy-Config-Id" type="string" required={true}>
+  Your Auth Proxy config ID, found in **Dashboard → AUTH**. See [Auth Proxy reference](/reference/auth-proxy) for setup.
+</ParamField>
+
+<H3Bordered text="Body" />
+
+<ParamField body="filterType" type="string" required={true}>
+
+Specifies the type of filter to apply, i.e 'CREDENTIAL_ID', 'NAME', 'USERNAME', 'EMAIL', 'PHONE_NUMBER', 'OIDC_TOKEN' or 'PUBLIC_KEY'
+</ParamField>
+
+<ParamField body="filterValue" type="string" required={true}>
+
+The value of the filter to apply for the specified type. For example, a specific email or name string.
+</ParamField>
+
+<ParamField body="verificationToken" type="string" required={false}>
+
+Signed JWT containing a unique id, expiry, verification type, contact. Used to verify access to PII (email/phone number) when filter_type is 'EMAIL' or 'PHONE_NUMBER'.
+</ParamField>
+
+<ParamField body="oidcToken" type="string" required={false}>
+
+OIDC token to verify access to PII (email/phone number) when filter_type is 'EMAIL' or 'PHONE_NUMBER'. Needed for social linking when verification_token is not available.
+</ParamField>
+
+
+<H3Bordered text="Response" />
+A successful response returns the following fields:
+
+<ResponseField name="organizationId" type="string" required={false}>organizationId field</ResponseField>
+
+<RequestExample>
+
+```bash title="cURL"
+curl --request POST \
+  --url https://authproxy.turnkey.com/v1/account \
+  --header 'Accept: application/json' \
+  --header 'Content-Type: application/json' \
+  --header "X-Auth-Proxy-Config-Id: <string> (see Authorizations)" \
+  --data '{
+    "filterType": "<string>",
+    "filterValue": "<string>",
+    "verificationToken": "<string>",
+    "oidcToken": "<string>"
+}'
+```
+
+</RequestExample>
+
+<ResponseExample>
+
+```json 200
+{
+  "organizationId": "<string>"
+}
+```
+
+</ResponseExample>
diff --git a/api-reference/auth-proxy/oauth-login.mdx b/api-reference/auth-proxy/oauth-login.mdx
@@ -0,0 +1,78 @@
+---
+title: "OAuth Login"
+description: "Login using an OIDC token and public key."
+---
+
+import { H3Bordered } from "/snippets/h3-bordered.mdx";
+import { NestedParam } from "/snippets/nested-param.mdx";
+
+<div class="flex w-full flex-col bg-background-light dark:bg-background-dark border-standard rounded-2xl p-1.5 mb-4">
+  <div class="flex items-center space-x-1.5">
+    <div class="relative flex-1 flex gap-2 min-w-0 rounded-xl items-center cursor-pointer p-1.5 border-standard">
+      <div class="rounded-lg font-bold px-1.5 py-0.5 text-sm leading-5 bg-blue-400/20 dark:bg-blue-400/20 text-blue-700 dark:text-blue-400">POST</div>
+      <div class="text-sm font-mono text-gray-800 dark:text-white">https://authproxy.turnkey.com/v1/oauth_login</div>
+    </div>
+  </div>
+</div>
+
+<H3Bordered text="Authorizations" />
+
+<ParamField header="X-Auth-Proxy-Config-Id" type="string" required={true}>
+  Your Auth Proxy config ID, found in **Dashboard → AUTH**. See [Auth Proxy reference](/reference/auth-proxy) for setup.
+</ParamField>
+
+<H3Bordered text="Body" />
+
+<ParamField body="oidcToken" type="string" required={true}>
+
+Base64 encoded OIDC token
+</ParamField>
+
+<ParamField body="publicKey" type="string" required={true}>
+
+Client-side public key generated by the user, which will be conditionally added to org data based on the validity of the oidc token associated with this request
+</ParamField>
+
+<ParamField body="invalidateExisting" type="boolean" required={false}>
+
+Invalidate all other previously generated Login API keys
+</ParamField>
+
+<ParamField body="organizationId" type="string" required={false}>
+
+Unique identifier for a given Organization. If provided, this organization id will be used directly. If omitted, uses the OIDC token to look up the associated organization id.
+</ParamField>
+
+
+<H3Bordered text="Response" />
+A successful response returns the following fields:
+
+<ResponseField name="session" type="string" required={true}>Signed JWT containing an expiry, public key, session type, user id, and organization id</ResponseField>
+
+<RequestExample>
+
+```bash title="cURL"
+curl --request POST \
+  --url https://authproxy.turnkey.com/v1/oauth_login \
+  --header 'Accept: application/json' \
+  --header 'Content-Type: application/json' \
+  --header "X-Auth-Proxy-Config-Id: <string> (see Authorizations)" \
+  --data '{
+    "oidcToken": "<string>",
+    "publicKey": "<string>",
+    "invalidateExisting": "<boolean>",
+    "organizationId": "<string>"
+}'
+```
+
+</RequestExample>
+
+<ResponseExample>
+
+```json 200
+{
+  "session": "<string>"
+}
+```
+
+</ResponseExample>
diff --git a/api-reference/auth-proxy/oauth2-authenticate.mdx b/api-reference/auth-proxy/oauth2-authenticate.mdx
@@ -0,0 +1,90 @@
+---
+title: "OAuth 2.0 Authenticate"
+description: "Authenticate with an OAuth 2.0 provider and receive an OIDC token issued by Turnkey in response."
+---
+
+import { H3Bordered } from "/snippets/h3-bordered.mdx";
+import { NestedParam } from "/snippets/nested-param.mdx";
+
+<div class="flex w-full flex-col bg-background-light dark:bg-background-dark border-standard rounded-2xl p-1.5 mb-4">
+  <div class="flex items-center space-x-1.5">
+    <div class="relative flex-1 flex gap-2 min-w-0 rounded-xl items-center cursor-pointer p-1.5 border-standard">
+      <div class="rounded-lg font-bold px-1.5 py-0.5 text-sm leading-5 bg-blue-400/20 dark:bg-blue-400/20 text-blue-700 dark:text-blue-400">POST</div>
+      <div class="text-sm font-mono text-gray-800 dark:text-white">https://authproxy.turnkey.com/v1/oauth2_authenticate</div>
+    </div>
+  </div>
+</div>
+
+<H3Bordered text="Authorizations" />
+
+<ParamField header="X-Auth-Proxy-Config-Id" type="string" required={true}>
+  Your Auth Proxy config ID, found in **Dashboard → AUTH**. See [Auth Proxy reference](/reference/auth-proxy) for setup.
+</ParamField>
+
+<H3Bordered text="Body" />
+
+<ParamField body="provider" type="enum<string>" required={true}>
+
+Enum options: `OAUTH2_PROVIDER_X`, `OAUTH2_PROVIDER_DISCORD`
+</ParamField>
+
+<ParamField body="authCode" type="string" required={true}>
+
+The auth_code provided by the OAuth 2.0 to the end user to be exchanged for a Bearer token in the OAuth 2.0 flow
+</ParamField>
+
+<ParamField body="redirectUri" type="string" required={true}>
+
+The URI the user is redirected to after they have authenticated with the OAuth 2.0 provider
+</ParamField>
+
+<ParamField body="codeVerifier" type="string" required={true}>
+
+The code verifier used by OAuth 2.0 PKCE providers
+</ParamField>
+
+<ParamField body="nonce" type="string" required={false}>
+
+An optional nonce used by the client to prevent replay/substitution of an ID token
+</ParamField>
+
+<ParamField body="clientId" type="string" required={true}>
+
+The client ID registered with the OAuth 2.0 provider
+</ParamField>
+
+
+<H3Bordered text="Response" />
+A successful response returns the following fields:
+
+<ResponseField name="oidcToken" type="string" required={true}>A Turnkey issued OIDC token to be used with the LoginWithOAuth activity</ResponseField>
+
+<RequestExample>
+
+```bash title="cURL"
+curl --request POST \
+  --url https://authproxy.turnkey.com/v1/oauth2_authenticate \
+  --header 'Accept: application/json' \
+  --header 'Content-Type: application/json' \
+  --header "X-Auth-Proxy-Config-Id: <string> (see Authorizations)" \
+  --data '{
+    "provider": "<OAUTH2_PROVIDER_X>",
+    "authCode": "<string>",
+    "redirectUri": "<string>",
+    "codeVerifier": "<string>",
+    "nonce": "<string>",
+    "clientId": "<string>"
+}'
+```
+
+</RequestExample>
+
+<ResponseExample>
+
+```json 200
+{
+  "oidcToken": "<string>"
+}
+```
+
+</ResponseExample>
diff --git a/api-reference/auth-proxy/otp-init.mdx b/api-reference/auth-proxy/otp-init.mdx
@@ -0,0 +1,68 @@
+---
+title: "Init OTP"
+description: "Start a new OTP flow and return a new OTP flow ID."
+---
+
+import { H3Bordered } from "/snippets/h3-bordered.mdx";
+import { NestedParam } from "/snippets/nested-param.mdx";
+
+<div class="flex w-full flex-col bg-background-light dark:bg-background-dark border-standard rounded-2xl p-1.5 mb-4">
+  <div class="flex items-center space-x-1.5">
+    <div class="relative flex-1 flex gap-2 min-w-0 rounded-xl items-center cursor-pointer p-1.5 border-standard">
+      <div class="rounded-lg font-bold px-1.5 py-0.5 text-sm leading-5 bg-blue-400/20 dark:bg-blue-400/20 text-blue-700 dark:text-blue-400">POST</div>
+      <div class="text-sm font-mono text-gray-800 dark:text-white">https://authproxy.turnkey.com/v1/otp_init_v2</div>
+    </div>
+  </div>
+</div>
+
+<H3Bordered text="Authorizations" />
+
+<ParamField header="X-Auth-Proxy-Config-Id" type="string" required={true}>
+  Your Auth Proxy config ID, found in **Dashboard → AUTH**. See [Auth Proxy reference](/reference/auth-proxy) for setup.
+</ParamField>
+
+<H3Bordered text="Body" />
+
+<ParamField body="otpType" type="string" required={true}>
+
+Enum to specify whether to send OTP code via SMS or email
+</ParamField>
+
+<ParamField body="contact" type="string" required={true}>
+
+Email or phone number to send the OTP code to
+</ParamField>
+
+
+<H3Bordered text="Response" />
+A successful response returns the following fields:
+
+<ResponseField name="otpId" type="string" required={true}>Unique identifier for an OTP flow.</ResponseField>
+<ResponseField name="otpEncryptionTargetBundle" type="string" required={true}>Signed bundle containing a target encryption key to use when submitting OTP codes.</ResponseField>
+
+<RequestExample>
+
+```bash title="cURL"
+curl --request POST \
+  --url https://authproxy.turnkey.com/v1/otp_init_v2 \
+  --header 'Accept: application/json' \
+  --header 'Content-Type: application/json' \
+  --header "X-Auth-Proxy-Config-Id: <string> (see Authorizations)" \
+  --data '{
+    "otpType": "<string>",
+    "contact": "<string>"
+}'
+```
+
+</RequestExample>
+
+<ResponseExample>
+
+```json 200
+{
+  "otpId": "<string>",
+  "otpEncryptionTargetBundle": "<string>"
+}
+```
+
+</ResponseExample>