Skip to main content

​
Overview

The Turnkey Auth Proxy is a managed, multi-tenant service that signs and forwards authentication requests (OTP, OAuth, signup/suborg creation) to the Turnkey Coordinator (Public API) on your behalf so you don’t need to host your own backend for auth.
  • Host: https://authproxy.turnkey.com
  • What it does: Validates origin, looks up your org’s proxy configuration, signs the request with a proxy-scoped API key, and forwards the request to Turnkey Coordinator.
  • What it doesn’t do: It cannot log in users without their participation (e.g., OTP code entry, OAuth consent). It doesn’t access funds or broader org operations.
Enable and configure the Auth Proxy from the Dashboard → AUTH section (allowed origins, templates, session lengths, etc).

​
When to Use the Auth Proxy

  • Use when you want backend-signed OTP/OAuth/signup flows with origin enforcement and central config. Your frontend calls Auth Proxy endpoints directly.

​
How It Works

  1. Enable in Dashboard. Toggle Auth Proxy ON. Turnkey creates a Proxy User and proxy API key, stored encrypted in the auth proxy config for your org.
  2. Configure Allowed Origins. Only requests from these origins may call the proxy (CORS + origin validation). By default all origins are allowed (*)
  3. Your App Calls Auth Proxy. Your frontend hits https://authproxy.turnkey.com/v1/... with your auth proxy config id and the flow parameters. This should be passed to the X-Auth-Proxy-Config-Id header in your request
  4. Proxy Signs & Forwards. Auth Proxy decrypts your proxy key in-memory, signs the activity, and forwards to Turnkey Coordinator.
  5. Coordinator Responds. Proxy returns success / error, plus any response payload (e.g., organizationId, session).
Security notes:
  • Proxy keys are HPKE encrypted inside our enclave; decrypted per request only in memory.
  • Strict separation from Turnkey’s core backend; communicates via public API only.
  • The Auth Proxy does not verify App Proofs produced by Turnkey’s secure enclaves, it simply passes them on to its caller. End-users (SDKs) are expected to perform this verification procedure, not the Auth Proxy. Refer to Turnkey Verified for more information on how App Proof verification works.

​
Base URL

All endpoints are under https://authproxy.turnkey.com

​
Authentication & Headers

  • Auth Proxy Config Id (required): identifies your parent org’s proxy config.
    • Send as header: 
      X-Auth-Proxy-Config-Id: <auth-proxy-config-token>
  • CORS & Origin: Requests must originate from a whitelisted origin set in the dashboard.

​
Endpoints

​
Signup (Create Sub-Organization)

POST /v1/signup Onboard a new user by creating a sub-organization. Optionally creates a wallet. Request Body 
{
  "userName": "[email protected]",
  "organizationName": "Example Org",
  "userEmail": "[email protected]",
  "apiKeys": [],
  "authenticators": [],
  "oauthProviders": [],
  "wallet": {
    "path": "m/44'/0'/0'/0/0",
    "curve": "CURVE_TYPE_ED25519"
  }
}
Response 
{
  "organizationId": "suborg-abc123"
}

​
Init OTP

POST /v1/otp_init Initialize an OTP (SMS or email) for a user. Request Body 
{
  "otpType": "OTP_TYPE_SMS",
  "contact": "+12265550123"
}
Response 
{
  "otpId": "otp-xyz789"
}

​
Verify OTP

POST /v1/otp_verify Verify the OTP code previously sent to the user’s contact. Request Body 
{
  "otpId": "otp-xyz789",
  "otpCode": "123456"
  "public_key": "02ab...compressedP256",
}
Response 
{
  "verificationToken": "verify-token-abc"
}

​
OTP Login

POST /v1/otp_login Login using a verification token and public key. Request Body 
{
  "verificationToken": "verify-token-abc",
  "publicKey": "02ab...compressedP256",
  "client_signature": "30453...hexEncodedSignatureOverVerificationToken",
"
}
Response 
{
  "session": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
}

​
OAuth2 Authenticate

POST /v1/oauth2_authenticate Authenticate with an OAuth 2.0 provider and receive an OIDC token issued by Turnkey in response. Request Body 
{
  "provider": "OAUTH2_PROVIDER_DISCORD",
  "authCode": "your_oauth2_auth_code",
  "redirectUri: "https://yourapp.com/callback",
  "codeVerifier": "string-used-for-pkce",
  "nonce":"sha256(publicKey)",
  "clientId":"your-oauth2-client-id",
}
Response 
{
  "oidcToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6.."
}

​
OAuth Login

POST /v1/oauth_login Login using an OIDC token and public key. Request Body 
{
  "oidcToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "publicKey": "02ab...compressedP256",
  "invalidateExisting": false
}
Response 
{
  "session": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
}

​
Get Account

POST /v1/account Return organization id associated with a given filter (e.g. email, phone, credential ID, OIDC token). Request Body 
{
  "filterType": "EMAIL",
  "filterValue": "[email protected]"
}
Response 
{
  "organizationId": "suborg-abc123"
}

​
Get Wallet Kit Config

POST /v1/wallet_kit_config Return Wallet Kit feature toggles for the calling organization. Request Body 
{}
Response 
{
  "enabledProviders": ["google", "facebook", "apple", "email", "sms", "passkey", "wallet"],
  "sessionExpirationSeconds": "1800",
  "organizationId": "org-abc123"
}

​
Configuration (Dashboard → AUTH)

  • Enable/Disable the Auth Proxy for your org
  • Allowed Frontend Origins (CORS enforcement)
  • Email/SMS Customization
  • Session Expiration