---
title: "Initiate Auth"
method: POST
path: "/v1/auth/initiate"
tags: ["Authentication"]
---

# Initiate Auth

`POST /v1/auth/initiate`

Start any authentication flow in one unified endpoint. This endpoint supports all authentication methods including SMS, email, OAuth, passkey, and SIWE (Sign-In with Ethereum).

**Supported Methods:**
- **SMS** - Send verification code to phone number
- **Email** - Send verification code to email address  
- **Passkey** - Generate WebAuthn challenge for biometric authentication
- **SIWE** - Generate Sign-In with Ethereum payload

**Flow:**
1. Choose your authentication method
2. Provide method-specific parameters
3. Receive challenge data to complete authentication
4. Use the /complete endpoint to finish the process

**OAuth:**

The OAuth method uses a dedicated `/auth/social` endpoint instead of this one:

`GET /auth/social?provider=google&redirectUrl=...`

**Custom (JWT, auth-payload) and Guest:**

For custom authentication (JWT, auth-payload) and for guest authentication, you can skip this step and use the `/auth/complete` endpoint directly.

**Authentication:** Requires `x-client-id` header for frontend usage or `x-secret-key` for backend usage.

## Request body

- union — Request to initiate authentication flow. Choose one of the supported authentication methods: sms, email, oauth, passkey, or siwe. The required fields depend on the authentication method selected.
  - object
    - `method` 'sms', required — Authentication method: SMS
    - `phone` string, required — Phone number in E.164 format (e.g., +1234567890)
  - object
    - `method` 'email', required — Authentication method: Email
    - `email` string, email, required — Email address for verification code
  - object
    - `method` 'oauth', required — Authentication method: OAuth
    - `provider` 'google' | 'apple' | 'facebook' | 'discord' | 'farcaster' | 'telegram' | 'line' | 'x' | 'coinbase' | 'github' | 'twitch' | 'steam' | 'tiktok' | 'epic', required — Social login provider
    - `redirectUrl` string, uri — Custom redirect URL after OAuth completion
  - object
    - `method` 'passkey', required — Authentication method: Passkey
    - `type` 'sign-up' | 'sign-in', required — Whether to create a new passkey or use existing one
    - `username` string — Username for passkey (optional, for identification)
  - object
    - `method` 'siwe', required — Authentication method: Sign-In with Ethereum
    - `address` string, required — Ethereum wallet address for SIWE
    - `chainId` integer — Chain ID for SIWE (defaults to 1)

## Response `200`

Authentication initiated successfully. Use the returned challenge data to complete authentication.

- union — Response from authentication initiation. Contains method-specific data needed to complete authentication.
  - object
    - `method` 'sms', required — Authentication method: SMS
    - `success` boolean, required — Whether the SMS code was sent successfully
  - object
    - `method` 'email', required — Authentication method: Email
    - `success` boolean, required — Whether the email code was sent successfully
  - object
    - `method` 'oauth', required — Authentication method: OAuth
    - `redirectUrl` string, uri, required — URL to redirect user for OAuth authentication
  - object
    - `method` 'passkey', required — Authentication method: Passkey
    - `serverVerificationId` string, required — Server verification ID for passkey
    - `challenge` string, required — Base64-encoded WebAuthn challenge
    - `type` string, required — Challenge type (sign-up or sign-in)
  - object
    - `method` 'siwe', required — Authentication method: Sign-In with Ethereum
    - `payload` string, required — SIWE message string to be signed

## Other responses

- `400` — Invalid request - Check your method and parameters
- `429` — Rate limit exceeded - Please wait before trying again

---

[API](https://skmtc.net/thirdweb/apis/thirdweb-api.md) · [All operations](https://skmtc.net/thirdweb/apis/thirdweb-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/thirdweb/thirdweb-api/revisions/fb4cb67da1c7/schema)