For email, phone, passkey, or SIWE authentication, a two-step process is used:
Initiate authentication to get a challenge
Complete authentication with the challenge response
For guest or custom (jwt/auth-payload) authentication, you can skip the first step and directly use the /v1/auth/complete endpoint with the required parameters.
Start authentication with email, phone, passkey, or SIWE
fetch('https://api.thirdweb.com/v1/auth/initiate', {
"method": "POST",
"headers": {
"x-client-id": "<your-project-client-id>"
},
"body": {
"method": "sms",
"phone": "string"
}
})
x-secret-keybackend
Project secret key - for backend usage only. Should not be used in frontend code.
x-client-idfrontend
Project client ID - for frontend usage on authorized domains.
x-ecosystem-idoptional
Ecosystem ID - for ecosystem wallets.
x-ecosystem-partner-idoptional
Ecosystem partner ID - for ecosystem wallets.
methodstring Required
Authentication method: SMS
phonestring Required
Phone number in E.164 format (e.g., +1234567890)
Verify and complete the authentication process:
fetch('https://api.thirdweb.com/v1/auth/complete', {
"method": "POST",
"headers": {
"x-client-id": "<your-project-client-id>"
},
"body": {
"method": "sms",
"phone": "string",
"code": "string"
}
})
x-secret-keybackend
Project secret key - for backend usage only. Should not be used in frontend code.
x-client-idfrontend
Project client ID - for frontend usage on authorized domains.
x-ecosystem-idoptional
Ecosystem ID - for ecosystem wallets.
x-ecosystem-partner-idoptional
Ecosystem partner ID - for ecosystem wallets.
methodstring Required
Authentication method: SMS
phonestring Required
Phone number that received the code
codestring Required
Verification code received via SMS
OAuth is done in a single step using a dedicated endpoint.
Visit the API reference for more details on the available social providers and code snippets.
x-secret-keybackend
Project secret key - for backend usage only. Should not be used in frontend code.
x-client-idfrontend
Project client ID - for frontend usage on authorized domains.
x-ecosystem-idoptional
Ecosystem ID - for ecosystem wallets.
x-ecosystem-partner-idoptional
Ecosystem partner ID - for ecosystem wallets.
providerstring Required
The OAuth provider to use
redirectUrlstring Required
URL to redirect the user to after OAuth completion
clientIdstring
Client ID (alternative to x-client-id header for standard OAuth flows)
Retrieve authenticated user's wallet details:
x-secret-keybackend
Project secret key - for backend usage only. Should not be used in frontend code.
x-client-idfrontend
Project client ID - for frontend usage on authorized domains.
x-ecosystem-idoptional
Ecosystem ID - for ecosystem wallets.
x-ecosystem-partner-idoptional
Ecosystem partner ID - for ecosystem wallets.
Social Authentication