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-key
backend
Project secret key - for backend usage only. Should not be used in frontend code.
x-client-id
frontend
Project client ID - for frontend usage on authorized domains.
x-ecosystem-id
optional
Ecosystem ID - for ecosystem wallets.
x-ecosystem-partner-id
optional
Ecosystem partner ID - for ecosystem wallets.
method
string Required
Authentication method: SMS
phone
string 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-key
backend
Project secret key - for backend usage only. Should not be used in frontend code.
x-client-id
frontend
Project client ID - for frontend usage on authorized domains.
x-ecosystem-id
optional
Ecosystem ID - for ecosystem wallets.
x-ecosystem-partner-id
optional
Ecosystem partner ID - for ecosystem wallets.
method
string Required
Authentication method: SMS
phone
string Required
Phone number that received the code
code
string 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-key
backend
Project secret key - for backend usage only. Should not be used in frontend code.
x-client-id
frontend
Project client ID - for frontend usage on authorized domains.
x-ecosystem-id
optional
Ecosystem ID - for ecosystem wallets.
x-ecosystem-partner-id
optional
Ecosystem partner ID - for ecosystem wallets.
provider
string Required
The OAuth provider to use
redirectUrl
string Required
URL to redirect the user to after OAuth completion
clientId
string
Client ID (alternative to x-client-id header for standard OAuth flows)
Retrieve authenticated user's wallet details:
x-secret-key
backend
Project secret key - for backend usage only. Should not be used in frontend code.
x-client-id
frontend
Project client ID - for frontend usage on authorized domains.
x-ecosystem-id
optional
Ecosystem ID - for ecosystem wallets.
x-ecosystem-partner-id
optional
Ecosystem partner ID - for ecosystem wallets.
Social Authentication