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.
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
- 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.
- Configure Allowed Origins. Only requests from these origins may call the proxy (CORS + origin validation). By default all origins are allowed (*)
- 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 - Proxy Signs & Forwards. Auth Proxy decrypts your proxy key in-memory, signs the activity, and forwards to Turnkey Coordinator.
- Coordinator Responds. Proxy returns success / error, plus any response payload (e.g., organizationId, session).
- 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.
Base URL
All endpoints are under https://authproxy.turnkey.comAuthentication & Headers
- Auth Proxy Config Id (required): identifies your parent org’s proxy config.
- Send as header:
- Send as header:
- 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
Init OTP
POST /v1/otp_init Initialize an OTP (SMS or email) for a user. Request BodyVerify OTP
POST /v1/otp_verify Verify the OTP code previously sent to the user’s contact. Request BodyOTP Login
POST /v1/otp_login Login using a verification token and public key. Request BodyOAuth2 Authenticate
POST /v1/oauth2_authenticate Authenticate with an OAuth 2.0 provider and receive an OIDC token issued by Turnkey in response. Request BodyOAuth Login
POST /v1/oauth_login Login using an OIDC token and public key. Request BodyGet Account
POST /v1/account Return organization id associated with a given filter (e.g. email, phone, credential ID, OIDC token). Request BodyGet Wallet Kit Config
POST /v1/wallet_kit_config Return Wallet Kit feature toggles for the calling organization. Request BodyConfiguration (Dashboard → AUTH)
- Enable/Disable the Auth Proxy for your org
- Allowed Frontend Origins (CORS enforcement)
- Email/SMS Customization
- Session Expiration