Explore the details of the Stytch API. Our authentication API is organized around REST principles and has resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Add a User to Stytch. A user_id is returned in the response that can then be used to perform other operations within Stytch. An email or a phone_number is required.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/users \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "sandbox@stytch.com"
}'RESPONSE
{
"status_code": 201,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user": {...},
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
"phone_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
"status": "active"
}Search for Users within your Stytch Project. Submit an empty query in the request to return all Users.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/users/search \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"limit": 200,
"cursor": "",
"query": {
"operator": "AND",
"operands": [
{
"filter_name": "phone_number",
"filter_value": ["+12025550162"]
},
]
}
}'RESPONSE
{
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"results": [
{
"created_at": "2021-12-17T04:02:28Z",
"crypto_wallets": [],
"emails": [
{
"email": "ghopper@stytch.com",
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
"verified": false
}
],
"name": {
"first_name": "Grace",
"last_name": "Hopper",
"middle_name": ""
},
"phone_numbers": [
{
"phone_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
"phone_number": "+12025550162",
"verified": true
}
],
"providers": [],
"status": "active",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"webauthn_registrations": []
},
{ ...more users... }
],
"results_metadata": {
"next_cursor": "eyJ2IjoxLCJsIjo0NjkzfQ==",
"total": 433
},
"status_code": 200
}`,
'200 - no more results': `{
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"results": [
{
"created_at": "2021-12-17T04:02:28Z",
"crypto_wallets": [],
"emails": [
{
"email": "ghopper@stytch.com",
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
"verified": false
}
],
"name": {
"first_name": "Grace",
"last_name": "Hopper",
"middle_name": ""
},
"phone_numbers": [
{
"phone_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
"phone_number": "+12025550162",
"verified": true
}
],
"providers": [],
"status": "active",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"webauthn_registrations": []
},
],
"results_metadata": {
"next_cursor": null,
"total": 1
},
"status_code": 200
}Get information about a specific User.
Path parameters
REQUEST
curl --request GET \
--url https://test.stytch.com/v1/users/user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"name": {
"first_name": "Jane",
"middle_name": "",
"last_name": "Doe"
},
"trusted_metadata": {
"shopify_cust_id":"207119551"
},
"untrusted_metadata": {
"onboarding_checklist": { "complete": true }
},
"emails": [
{
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
"email": "test@example.com",
"verified": true
}
],
"phone_numbers": [
{
"phone_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
"phone_number": "+12025550162",
"verified": true
}
],
"providers": [
{
"oauth_user_registration_id": "oauth-user-test-de86770c-911d-463f-80e7-f1b089cead14",
"provider_subject": "10769150350006150715113082367",
"provider_type": "Google",
"profile_picture_url": "example.com",
"locale": "en"
}
],
"webauthn_registrations": [
{
"webauthn_registration_id": "webauthn-registration-test-5c44cc6a-8af7-48d6-8da7-ea821342f5a6",
"domain": "example.com",
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
"authenticator_type": "platform",
"verified": true
}
],
"biometric_registrations": [
{
"biometric_registration_id": "biometric-registration-test-6966a6fc-5264-46ee-9ba4-98c6322a5134",
"verified": true
}
],
"totps": [
{
"totp_id": "totp-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c",
"verified": true
}
],
"crypto_wallets": [
{
"crypto_wallet_id": "crypto-wallet-test-dbbd372e-79f8-48ea-907c-5f0755e7d328",
"crypto_wallet_address": "0x6df2dB4Fb3DA35d241901Bd53367770BF03123f1",
"crypto_wallet_type": "ethereum",
"verified": true
}
],
"password": {
"password_id": "password-test-ca6dbe77-10e5-4403-805a-b117c55c24c6",
"requires_reset": false
},
"created_at": "2021-11-14T21:30:23Z",
"status": "active"
}Update a User's attributes.
Note: In order to add a new email address or phone number to an existing User object, pass the new email address or phone number into the respective /send endpoint for the authentication method of your choice. If you specify the existing User's user_id while calling the /send endpoint, the new email address or phone number will be added to the existing User object upon successful authentication. We require this process to guard against an account takeover vulnerability.
Path parameters
REQUEST
curl --request PUT \
--url https://test.stytch.com/v1/users/user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"name": {
"first_name": "Jane",
"last_name": "Doe"
},
"trusted_metadata": {
"role": "ADMIN"
}
}'RESPONSE
{
"emails": [
{
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
"email": "sandbox@stytch.com",
"verified": false
}
],
"phone_numbers": [
{
"phone_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
"phone_number": "+12025550162",
"verified": false
}
],
"crypto_wallets": [
{
"crypto_wallet_id": "crypto-wallet-test-dbbd372e-79f8-48ea-907c-5f0755e7d328",
"crypto_wallet_address": "0x6df2dB4Fb3DA35d241901Bd53367770BF03123f1",
"crypto_wallet_type": "ethereum",
"verified": true
}
],
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"status_code": 200,
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user": {...}
}Delete a User from Stytch.
Path parameters
REQUEST
curl --request DELETE \
--url https://test.stytch.com/v1/users/user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
}Delete an email from a User.
Path parameters
REQUEST
curl --request DELETE \
--url https://test.stytch.com/v1/users/emails/email-test-81bf03a8-86e1-4d95-bd44-bb3495224953 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user": {...}
}Delete a phone number from a User.
Path parameters
REQUEST
curl --request DELETE \
--url https://test.stytch.com/v1/users/phone_numbers/phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user": {...}
}Delete a WebAuthn registration from a User.
Path parameters
REQUEST
curl --request DELETE \
--url https://test.stytch.com/v1/users/webauthn_registrations/webauthn-registration-test-5c44cc6a-8af7-48d6-8da7-ea821342f5a6 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user": {...}
}Delete a biometric registration from a User.
Path parameters
REQUEST
curl --request DELETE \
--url https://test.stytch.com/v1/users/biometric_registrations/biometric-registration-test-6966a6fc-5264-46ee-9ba4-98c6322a5134 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user", {...}
}Delete a TOTP from a User.
Path parameters
REQUEST
curl --request DELETE \
--url https://test.stytch.com/v1/users/totps/totp-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user": {...}
}Delete a crypto wallet from a User.
Path parameters
REQUEST
curl --request DELETE \
--url https://test.stytch.com/v1/users/crypto_wallets/crypto-wallet-test-dbbd372e-79f8-48ea-907c-5f0755e7d328 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user": {...}
}Delete a password from a User.
Path parameters
REQUEST
curl --request DELETE \
--url https://test.stytch.com/v1/users/passwords/password-test-ca6dbe77-10e5-4403-805a-b117c55c24c6 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user": {...}
}Delete an OAuth registration from a User.
Path parameters
REQUEST
curl --request DELETE \
--url https://test.stytch.com/v1/users/oauth/oauth-user-test-de86770c-911d-463f-80e7-f1b089cead14 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user": {...}
}Send a magic link to an existing Stytch user using their email address. If you'd like to create a user and send them a magic link by email with one request, use our log in or create endpoint.
This endpoint also allows you to add a new email to an existing Stytch User. Including a user_id, session_token, or session_jwt in the request will add the email to the pre-existing Stytch User upon successful authentication.
Adding a new email to an existing Stytch User requires the user to be present and validate the email via magic link. This requirement is in place to prevent account takeover attacks.
The user is emailed a magic link which redirects them to the provided redirect URL. Collect the token from the URL query parameters, and call Authenticate magic link to complete authentication.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/magic_links/email/send \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "sandbox@stytch.com"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
}Send either a login or signup Magic Link to the User based on if the email is associated with a User already. A new or pending User will receive a signup Magic Link. An active User will receive a login Magic Link. For more information on how to control the status your Users are created in see the create_user_as_pending flag.
The User is emailed a Magic Link which redirects them to the provided redirect URL. Collect the token from the URL query parameters and call Authenticate Magic Link to complete authentication.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/magic_links/email/login_or_create \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "sandbox@stytch.com"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
"user_created": true
}Create a User and send an invite Magic Link to the provided email. The User will be created with a pending status until they click the Magic Link in the invite email.
The User is emailed a Magic Link which redirects them to the provided redirect URL. Collect the token from the URL query parameters and call Authenticate Magic Link to complete authentication.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/magic_links/email/invite \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "sandbox@stytch.com"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
}Revoke a pending invite based on the email provided.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/magic_links/email/revoke_invite \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "sandbox@stytch.com"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141"
}With our out-of-the-box Email Magic Links product, Stytch is able to fully handle the frustrating and complex pieces of email deliverability, latency, and inbox placement. However, we also offer a flexible way for you to embed Magic Links into any use case you can imagine. For example, you could send Magic Links from your own domain, embed them into customized templates, or leverage different communication channels, like SMS, to send them.
By using our Magic Link Create endpoint, you can embed Magic Links into all of your end user communications to reduce friction and improve conversion. If needed, you can always add more authentication requirements to a User’s session to improve security by using the rest of Stytch’s product suite.
Create an embeddable Magic Link token for a User. Access to this endpoint is restricted. To enable it, please send us a note at support@stytch.com.
Send the returned token value to the end user in a link which directs to your application. When the end user follows your link, collect the token, and call Authenticate Magic Link to complete authentication.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/magic_links \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4="
}Authenticate a User given a Magic Link. This endpoint verifies that the Magic Link token is valid, hasn't expired or been previously used, and any optional security settings such as IP match or user agent match are satisfied.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/magic_links/authenticate \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4="
}'RESPONSE
{
"method_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"reset_sessions": false,
"session": null,
"session_jwt": "",
"session_token": "",
"status_code": 200,
"user": {...},
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
}SMS OTP sends a one-time passcode to the User's phone number. This endpoint allows for a quick and seamless login experience on its own or it can also be layered on top of another login product, like Email Magic Links, to provide extra security as a multi-factor authentication (MFA) method.
Countries that we do not support for SMS OTP may be found here.
Send a one-time passcode (OTP) to a user's phone number. If you'd like to create a user and send them a passcode with one request, use our log in or create endpoint.
Note that sending another OTP code before the first has expired will invalidate the first code.
This endpoint also allows you to add a new phone number to an existing Stytch User. Including a user_id, session_token, or session_jwt in the request will add the phone number to the pre-existing Stytch User upon successful authentication.
Adding a new phone number to an existing Stytch User requires the user to be present and validate the phone number via OTP. This requirement is in place to prevent account takeover attacks.
Collect the OTP which was delivered to the user. Call Authenticate OTP using the OTP code along with the phone_id found in the response as the method_id.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/otps/sms/send \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"phone_number": "+12025550162"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"phone_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0"
}Send a one-time passcode (OTP) to a User using their phone number. If the phone number is not associated with a user already, a user will be created.
Collect the OTP which was delivered to the User. Call Authenticate OTP using the OTP code along with the phone_id found in the response as the method_id.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/otps/sms/login_or_create \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"phone_number": "+12025550162"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"phone_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
"user_created": true
}Send a one-time passcode (OTP) to a User's WhatsApp. If you'd like to create a user and send them a passcode with one request, use our log in or create endpoint.
Note that sending another OTP code before the first has expired will invalidate the first code.
This endpoint also allows you to add a new phone number to an existing Stytch User. Including a user_id, session_token, or session_jwt in the request will add the phone number to the pre-existing Stytch User upon successful authentication.
Adding a new phone number to an existing Stytch User requires the user to be present and validate the phone number via OTP. This requirement is in place to prevent account takeover attacks.
Collect the OTP which was delivered to the user. Call Authenticate OTP using the OTP code along with the phone_id found in the response as the method_id.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/otps/whatsapp/send \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"phone_number": "+12025550162"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"phone_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0"
}Send a one-time passcode (OTP) to a User's WhatsApp using their phone number. If the phone number is not associated with a User already, a User will be created.
Collect the OTP which was delivered to the User. Call Authenticate OTP using the OTP code along with the phone_id found in the response as the method_id.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/otps/whatsapp/login_or_create \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"phone_number": "+12025550162"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"phone_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
"user_created": true
}Email passcodes sends a one-time passcode (OTP) to the User's email address. The User will then submit that code to your app.
Send a one-time passcode (OTP) to a User using their email. If you'd like to create a user and send them a passcode with one request, use our log in or create endpoint.
This endpoint also allows you to add a new email to an existing Stytch User. Including a user_id, session_token, or session_jwt in the request will add the email to the pre-existing Stytch User upon successful authentication.
Adding a new email to an existing Stytch User requires the User to be present and validate the email via OTP. This requirement is in place to prevent account takeover attacks.
Collect the OTP which was delivered to the user. Call Authenticate OTP using the OTP code along with the phone_id found in the response as the method_id.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/otps/email/send \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "sandbox@stytch.com"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
}Send a one-time passcode (OTP) to a User using their email. If the email is not associated with a User already, a User will be created.
Collect the OTP which was delivered to the User. Call Authenticate OTP using the OTP code along with the phone_id found in the response as the method_id.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/otps/email/login_or_create \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "sandbox@stytch.com"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
"user_created": true
}Authenticate a User given a method_id (the associated email_id or phone_id) and a code. This endpoint verifies that the code is valid, hasn't expired or been previously used, and any optional security settings such as IP match or user agent match are satisfied. A given method_id may only have a single active OTP code at any given time, if a User requests another OTP code before the first one has expired, the first one will be invalidated.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/otps/authenticate \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"method_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
"code": "123456"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user": {...},
"method_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
"reset_sessions": false,
"session_jwt": "",
"session_token": "",
"session": null
}OAuth is a popular authentication framework that delegates authentication to an external identity provider (often shortened to IdP) like Google, Facebook, Apple, and Microsoft. A user relies on their membership from that provider to sign in instead of creating another password, and developers can enrich their users' experiences with the information shared by the providers. While OAuth has many benefits, developers need to understand the OAuth framework well to implement it securely. Stytch's OAuth product simplifies the process by abstracting the implementation details of OAuth for developers. The steps for an OAuth flow are simple:
Generate an OAuth Attach Token to pre-associate an OAuth flow with an existing Stytch User. Pass the returned oauth_attach_token to the same provider's OAuth Start endpoint to treat this OAuth flow as a login for that user instead of a signup for a new user.
Exactly one of user_id, session_token, and session_jwt must be provided to identify the target Stytch User.
This is an optional step in the OAuth flow. Stytch can often determine whether to create a new user or log in an existing one based on verified identity provider information. This endpoint is useful for cases where we can't, such as missing or unverified provider information.
REQUEST
curl --request POST \\
--url https://test.stytch.com/v1/oauth/attach \\
-u 'PROJECT_ID:SECRET' \\
-H 'Content-Type: application/json' \\
-d '{
"provider": "google",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"oauth_attach_token": "...",
}A client-side endpoint (can only be queried from the user's browser) that starts the Google OAuth flow. This endpoint generates the Google OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Google Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_url or signup_redirect_url URLs provided.
By default our Google OAuth integration includes open_id, email, and profile scopes. You may add any additional Google API scopes, see here for a complete list, as a space separated list in the custom_scopes query parameter of /oauth/google/start.
Once the user successfully authenticates with Google, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth token to complete authentication.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/public/oauth/google/start?public_token=PUBLIC_TOKEN&login_redirect_url={login_redirect_url}&signup_redirect_url={signup_redirect_url}'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://accounts.google.com/o/oauth2/v2/auth/identifier?client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=openid%20email%20profile&access_type=offline&state=example-state",
}A client-side endpoint (can only be queried from the user's browser) that starts the Amazon OAuth flow. This endpoint generates the Amazon OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Amazon Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_url or signup_redirect_url URLs provided.
By default our Amazon OAuth integration includes open_id, email, and profile scopes. You may add any additional Amazon API scopes, see here for a complete list, as a space separated list in the custom_scopes query parameter of /oauth/amazon/start.
Once the user successfully authenticates with Amazon, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth token to complete authentication.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/public/oauth/google/start?public_token=PUBLIC_TOKEN&login_redirect_url={login_redirect_url}&signup_redirect_url={signup_redirect_url}'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://amazon.com/api/oauth2/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=identify%3Aemail&state=example-state",
}A client-side endpoint (can only be queried from the user's browser) that starts the Apple OAuth flow. This endpoint generates the Apple OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Apple Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_url or signup_redirect_url URLs provided.
By default our apple OAuth integration includes open_id, email, and profile scopes. You may add any additional apple API scopes, see here for a complete list, as a space separated list in the custom_scopes query parameter of /oauth/apple/start.
Once the user successfully authenticates with Apple, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth token to complete authentication.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/public/oauth/apple/start?public_token=PUBLIC_TOKEN&login_redirect_url={login_redirect_url}&signup_redirect_url={signup_redirect_url}'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://appleid.apple.com/auth/authorize?client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&response_mode=form_post&scope=name%20email&state=example-state",
}A client-side endpoint (can only be queried from the user's browser) that starts the Bitbucket OAuth flow. This endpoint generates the Bitbucket OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Bitbucket Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_url or signup_redirect_url URLs provided.
By default our Bitbucket OAuth integration includes open_id, email, and profile scopes. You may add any additional Bitbucket API scopes, see here for a complete list, as a space separated list in the custom_scopes query parameter of /oauth/bitbucket/start.
Once the user successfully authenticates with Bitbucket, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth token to complete authentication.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/public/oauth/bitbucket/start?public_token=PUBLIC_TOKEN&login_redirect_url={login_redirect_url}&signup_redirect_url={signup_redirect_url}'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://bitbucket.com/api/oauth2/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=identify%3Aemail&state=example-state",
}A client-side endpoint (can only be queried from the user's browser) that starts the Coinbase OAuth flow. This endpoint generates the Coinbase OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Coinbase Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_url or signup_redirect_url URLs provided.
By default our Coinbase OAuth integration includes open_id, email, and profile scopes. You may add any additional Coinbase API scopes, see here for a complete list, as a space separated list in the custom_scopes query parameter of /oauth/coinbase/start.
Once the user successfully authenticates with Coinbase, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth token to complete authentication.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/public/oauth/coinbase/start?public_token=PUBLIC_TOKEN&login_redirect_url={login_redirect_url}&signup_redirect_url={signup_redirect_url}'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://coinbase.com/api/oauth2/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=identify%3Aemail&state=example-state",
}A client-side endpoint (can only be queried from the user's browser) that starts the Discord OAuth flow. This endpoint generates the Discord OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Discord Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_url or signup_redirect_url URLs provided.
By default our Discord OAuth integration includes open_id, email, and profile scopes. You may add any additional Discord API scopes, see here for a complete list, as a space separated list in the custom_scopes query parameter of /oauth/discord/start.
Once the user successfully authenticates with Discord, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth token to complete authentication.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/public/oauth/discord/start?public_token=PUBLIC_TOKEN&login_redirect_url={login_redirect_url}&signup_redirect_url={signup_redirect_url}'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://discord.com/api/oauth2/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=identify%3Aemail&state=example-state",
}A client-side endpoint (can only be queried from the user's browser) that starts the Facebook OAuth flow. This endpoint generates the Facebook OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Facebook Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_url or signup_redirect_url URLs provided.
By default our Facebook OAuth integration includes open_id, email, and profile scopes. You may add any additional Facebook API scopes, see here for a complete list, as a space separated list in the custom_scopes query parameter of /oauth/facebook/start.
Once the user successfully authenticates with Facebook, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth token to complete authentication.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/public/oauth/facebook/start?public_token=PUBLIC_TOKEN&login_redirect_url={login_redirect_url}&signup_redirect_url={signup_redirect_url}'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://www.facebook.com/v12.0/dialog/oauth?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=email+public_profile&state=example-state",
}A client-side endpoint (can only be queried from the user's browser) that starts the Figma OAuth flow. This endpoint generates the Figma OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Figma Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_url or signup_redirect_url URLs provided.
By default our Figma OAuth integration includes open_id, email, and profile scopes. You may add any additional Figma API scopes, see here for a complete list, as a space separated list in the custom_scopes query parameter of /oauth/figma/start.
Once the user successfully authenticates with Figma, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth token to complete authentication.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/public/oauth/figma/start?public_token=PUBLIC_TOKEN&login_redirect_url={login_redirect_url}&signup_redirect_url={signup_redirect_url}'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://www.figma.com/oauth?access_type=offline&client_id=M1M5R3BMVy13QmpScXkzTUt5OE46MTpjaQ&redirect_uri=https%3A%2F%2Ftest.stytch.com%2Fv1%2Foauth%2Fcallback%2Foauth-callback-test-7ead456f-7871-47a3-9ee5-f0002b03d05f&response_type=code&scope=file_read&state=Figma%3ASQ8MiSdQy1UmZ1sdMkcC1T28bOr2qvO-3-LtuidPd8kX",
}A client-side endpoint (can only be queried from the user's browser) that starts the Github OAuth flow. This endpoint generates the Github OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Github Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_url or signup_redirect_url URLs provided.
By default our Github OAuth integration includes open_id, email, and profile scopes. You may add any additional Github API scopes, see here for a complete list, as a space separated list in the custom_scopes query parameter of /oauth/github/start.
Once the user successfully authenticates with Github, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth token to complete authentication.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/public/oauth/github/start?public_token=PUBLIC_TOKEN&login_redirect_url={login_redirect_url}&signup_redirect_url={signup_redirect_url}'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://github.com/login/oauth/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=user%3Aemail&state=example-state",
}A client-side endpoint (can only be queried from the user's browser) that starts the Gitlab OAuth flow. This endpoint generates the Gitlab OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Gitlab Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_url or signup_redirect_url URLs provided.
By default our Gitlab OAuth integration includes open_id, email, and profile scopes. You may add any additional Gitlab API scopes, see here for a complete list, as a space separated list in the custom_scopes query parameter of /oauth/gitlab/start.
Once the user successfully authenticates with Gitlab, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth token to complete authentication.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/public/oauth/gitlab/start?public_token=PUBLIC_TOKEN&login_redirect_url={login_redirect_url}&signup_redirect_url={signup_redirect_url}'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://gitlab.com/login/oauth/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=user%3Aemail&state=example-state",
}A client-side endpoint (can only be queried from the user's browser) that starts the Linkedin OAuth flow. This endpoint generates the Linkedin OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Linkedin Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_url or signup_redirect_url URLs provided.
By default our Linkedin OAuth integration includes open_id, email, and profile scopes. You may add any additional Linkedin API scopes, see here for a complete list, as a space separated list in the custom_scopes query parameter of /oauth/linkedin/start.
Once the user successfully authenticates with Linkedin, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth token to complete authentication.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/public/oauth/linkedin/start?public_token=PUBLIC_TOKEN&login_redirect_url={login_redirect_url}&signup_redirect_url={signup_redirect_url}'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://linkedin.com/api/oauth2/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=identify%3Aemail&state=example-state",
}A client-side endpoint (can only be queried from the user's browser) that starts the Microsoft OAuth flow. This endpoint generates the Microsoft OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Microsoft Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_url or signup_redirect_url URLs provided.
By default our Microsoft OAuth integration includes open_id, email, and profile scopes. You may add any additional Microsoft API scopes, see here for a complete list, as a space separated list in the custom_scopes query parameter of /oauth/microsoft/start.
Once the user successfully authenticates with Microsoft, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth token to complete authentication.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/public/oauth/microsoft/start?public_token=PUBLIC_TOKEN&login_redirect_url={login_redirect_url}&signup_redirect_url={signup_redirect_url}'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=openid+email+profile&state=example-state",
}A client-side endpoint (can only be queried from the user's browser) that starts the Salesforce OAuth flow. This endpoint generates the Salesforce OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Salesforce Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_url or signup_redirect_url URLs provided.
By default our Salesforce OAuth integration includes open_id, email, and profile scopes. You may add any additional Salesforce API scopes, see here for a complete list, as a space separated list in the custom_scopes query parameter of /oauth/salesforce/start.
Once the user successfully authenticates with Salesforce, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth token to complete authentication.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/public/oauth/salesforce/start?public_token=PUBLIC_TOKEN&login_redirect_url={login_redirect_url}&signup_redirect_url={signup_redirect_url}'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://salesforce.com/api/oauth2/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=identify%3Aemail&state=example-state",
}A client-side endpoint (can only be queried from the user's browser) that starts the Slack OAuth flow. This endpoint generates the Slack OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Slack Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_url or signup_redirect_url URLs provided.
By default our Slack OAuth integration includes open_id, email, and profile scopes. You may add any additional Slack API scopes, see here for a complete list, as a space separated list in the custom_scopes query parameter of /oauth/slack/start.
Once the user successfully authenticates with Slack, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth token to complete authentication.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/public/oauth/slack/start?public_token=PUBLIC_TOKEN&login_redirect_url={login_redirect_url}&signup_redirect_url={signup_redirect_url}'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://slack.com/oauth/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=openid%3Aprofile%3Aemail&state=example-state",
}A client-side endpoint (can only be queried from the user's browser) that starts the Snapchat OAuth flow. This endpoint generates the Snapchat OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Snapchat Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_url or signup_redirect_url URLs provided.
By default our Snapchat OAuth integration includes open_id, email, and profile scopes. You may add any additional Snapchat API scopes, see here for a complete list, as a space separated list in the custom_scopes query parameter of /oauth/snapchat/start.
Once the user successfully authenticates with Snapchat, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth token to complete authentication.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/public/oauth/snapchat/start?public_token=PUBLIC_TOKEN&login_redirect_url={login_redirect_url}&signup_redirect_url={signup_redirect_url}'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://accounts.snapchat.com/accounts/oauth2/auth?access_type=offline&client_id=M1M5R3BMVy13QmpScXkzTUt5OE46MTpjaQ&redirect_uri=https%3A%2F%2Ftest.stytch.com%2Fv1%2Foauth%2Fcallback%2Foauth-callback-test-7ead456f-7871-47a3-9ee5-f0002b03d05f&response_type=code&scope=https%3A%2F%2Fauth.snapchat.com%2Foauth2%2Fapi%2Fuser.display_name+https%3A%2F%2Fauth.snapchat.com%2Foauth2%2Fapi%2Fuser.bitmoji.avatar+https%3A%2F%2Fauth.snapchat.com%2Foauth2%2Fapi%2Fuser.external_id&state=Snapchat%3AW_jLEECBVSRY0yc8i3UG_h-4k95V1K90LlXuWBATL2KM",
}A client-side endpoint (can only be queried from the user's browser) that starts the Tiktok OAuth flow. This endpoint generates the Tiktok OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Tiktok Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_url or signup_redirect_url URLs provided.
By default our Tiktok OAuth integration includes open_id, email, and profile scopes. You may add any additional Tiktok API scopes, see here for a complete list, as a space separated list in the custom_scopes query parameter of /oauth/tiktok/start.
Once the user successfully authenticates with Tiktok, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth token to complete authentication.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/public/oauth/tiktok/start?public_token=PUBLIC_TOKEN&login_redirect_url={login_redirect_url}&signup_redirect_url={signup_redirect_url}'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://www.tiktok.com/auth/authorize/?client_key={CLIENT_KEY}&scope=user.info.basic,video.list&response_type=code&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&state=2t6878vioue",
}A client-side endpoint (can only be queried from the user's browser) that starts the Twitch OAuth flow. This endpoint generates the Twitch OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Twitch Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_url or signup_redirect_url URLs provided.
By default our Twitch OAuth integration includes open_id, email, and profile scopes. You may add any additional Twitch API scopes, see here for a complete list, as a space separated list in the custom_scopes query parameter of /oauth/twitch/start.
Once the user successfully authenticates with Twitch, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth token to complete authentication.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/public/oauth/twitch/start?public_token=PUBLIC_TOKEN&login_redirect_url={login_redirect_url}&signup_redirect_url={signup_redirect_url}'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://twitch.com/api/oauth2/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=identify%3Aemail&state=example-state",
}A client-side endpoint (can only be queried from the user's browser) that starts the Twitter OAuth flow. This endpoint generates the Twitter OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Twitter Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_url or signup_redirect_url URLs provided.
By default our Twitter OAuth integration includes open_id, email, and profile scopes. You may add any additional Twitter API scopes, see here for a complete list, as a space separated list in the custom_scopes query parameter of /oauth/twitter/start.
Once the user successfully authenticates with Twitter, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth token to complete authentication.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/public/oauth/twitter/start?public_token=PUBLIC_TOKEN&login_redirect_url={login_redirect_url}&signup_redirect_url={signup_redirect_url}'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://twitter.com/i/oauth2/authorize?response_type=code&client_id=M1M5R3BMVy13QmpScXkzTUt5OE46MTpjaQ&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&scope=users.read&state=state&code_challenge=challenge&code_challenge_method=plain",
}Authenticate a User given a token. This endpoint verifies that the user completed the OAuth flow by verifying that the token is valid and hasn't expired. To initiate a Stytch session for the user while authenticating their OAuth token, include session_duration_minutes; a session with the identity provider, e.g. Google or Facebook, will always be initiated upon successful authentication.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/oauth/authenticate \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"token": "hdPVZHHX0UoRa7hJTuuPHi1vlddffSnoweRbVFf5-H8g",
"session_duration_minutes": 60
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user": {...},
"oauth_user_registration_id": "oauth-user-test-de86770c-911d-463f-80e7-f1b089cead14",
"provider_subject": "10769150350006150715113082367",
"provider_type": "Google"
"provider_values": {
"access_token": "example-access-token",
"refresh_token": "example-refresh-token",
"id_token": "example-id-token",
"scopes": ["example scope"]
},
"reset_sessions": false,
"session": {
...Stytch session...
},
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
"session_jwt": "example_jwt"
}Stytch user sessions are identified by a session_token or session_jwt that should be stored client-side (usually a browser cookie) and authenticated on each request. To start a session, use the authenticate magic link or authenticate OTP endpoint as usual and add the session_duration_minutes parameter to set the lifetime of the session. Look for session_token and session_jwt in the response.
Get the JSON Web Key Set (JWKS) for a Stytch Project.
Path parameters
REQUEST
curl --request GET \
--url https://test.stytch.com/v1/sessions/jwks/PROJECT_IDRESPONSE
{
"status_code": 200,
"keys": [
{
"alg": "RS256",
"e": "example-e",
"key_ops": ["verify"],
"kid": "example-key-id",
"kty": "RSA",
"n": "example-n",
"use": "sig",
"x5c": ["example-x5c"],
"x5tS256": "example-x5tS256",
},
],
}List all active Sessions for a given user_id. All timestamps are formatted according to the RFC 3339 standard and are expressed in UTC, e.g. 2021-12-29T12:33:09Z.
REQUEST
curl --request GET \
--url https://test.stytch.com/v1/sessions \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
--get \
--data-urlencode 'user_id=user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"sessions": [
{
"attributes": {
"ip_address": "203.0.113.1",
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"
},
"authentication_factors": [
{
"delivery_method": "email",
"email_factor": {
"email_address": "sandbox@stytch.com",
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
},
"last_authenticated_at": "2021-08-09T07:41:52Z",
"type": "magic_link"
}
],
"custom_claims": {
"claim1": "value1",
"claim2": "value2",
},
"expires_at": "2021-08-10T07:41:52Z",
"last_accessed_at": "2021-08-09T07:41:52Z",
"session_id": "session-test-fe6c042b-6286-479f-8a4f-b046a6c46509",
"started_at": "2021-08-09T07:41:52Z",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
}
],
}Authenticate a session token and retrieve associated session data. If session_duration_minutes is included, update the lifetime of the session to be that many minutes from now. All timestamps are formatted according to the RFC 3339 standard and are expressed in UTC, e.g. 2021-12-29T12:33:09Z. This endpoint requires exactly one session_jwt or session_token as part of the request. If both are included you will receive a too_many_session_arguments error.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/sessions/authenticate \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"session": {
"attributes": {
"ip_address": "203.0.113.1",
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"
},
"authentication_factors": [
{
"delivery_method": "email",
"email_factor": {
"email_address": "sandbox@stytch.com",
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
},
"last_authenticated_at": "2021-08-09T07:41:52Z",
"type": "magic_link"
}
],
"custom_claims": {
"claim1": "value1",
"claim2": "value2",
},
"expires_at": "2021-08-10T07:41:52Z",
"last_accessed_at": "2021-08-09T07:41:52Z",
"session_id": "session-test-fe6c042b-6286-479f-8a4f-b046a6c46509",
"started_at": "2021-08-09T07:41:52Z",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
},
"session_jwt": "example_jwt"
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q"
"user": {...},
}Revoke a Session, immediately invalidating all of its session tokens. You can revoke a session in three ways: using its ID, or using one of its session tokens, or one of its JWTs. This endpoint requires exactly one of those to be included in the request. It will return an error if multiple are present.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/sessions/revoke \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"session_id": "session-test-fe6c042b-6286-479f-8a4f-b046a6c46509"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141"
}The Web Authentication API (WebAuthn) is a specification that allows web applications on supported browsers to authenticate a user via authenticator types such as built-in device biometrics (e.g. facial recognition on mobile and fingerprint readers on desktop) or secure hardware keys (e.g. YubiKeys). While WebAuthn has many benefits, developers need to understand the API to implement it securely. Stytch's WebAuthn product simplifies the process by abstracting the implementation details of WebAuthn for developers to make it as quick as possible to implement securely.
There are two steps during a WebAuthn authentication flow, registration and authentication. The first step handles registering a WebAuthn device to a user. The second step handles the authentication attempt.
For both the registration and authentication steps, you’ll make two Stytch requests. The first request returns the necessary components to communicate with the WebAuthn device. The second request is used to pass the response from the WebAuthn call back to Stytch for verification.
You can read an in depth guide here.
Initiate the process of creating a new WebAuthn registration. After calling this endpoint, the browser will need to call navigator.credentials.create() with the data from public_key_credential_creation_options passed to the navigator.credentials.create() request via the public key argument. We recommend using the create() wrapper provided by the webauthn-json library.
If you are not using the webauthn-json library, the public_key_credential_creation_options will need to be converted to a suitable public key by unmarshalling the JSON, base64 decoding the user ID field, and converting user ID and the challenge fields into an array buffer.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/webauthn/authenticate/start \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
"domain": "example.com"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"public_key_credential_request_options": "{\"allowCredentials\":[{\"id\":\"AUnfDtA+myCDdumkKnVp2Sk0MIWCPXQVL2mG3h+xQBvLEF+MmNqvj2ZwNIY8id5UHz7ogZKmGgc0mM9yYVhdJNU1n6nIwPBGUuZpr3N18trqXMKxejYYKwCO4BmSHA==\",\"type\":\"public-key\"},],\"challenge\":\"hYZtLNT9SIgZqPnKfbnQX3nCJ7NavTT_S6oC9XREYv0F\",\"rpId\":\"example.com\",\"timeout\":300000,\"userVerification\":\"discouraged\"}"
}Complete the creation of a WebAuthn registration by passing the response from the navigator.credentials.create() request to this endpoint as the public_key_credential parameter.
If the webauthn-json library's create() method was used, the response can be passed directly to the register endpoint. If not, some fields (the client data and the attestation object) from the navigator.credentials.create() response will need to be converted from array buffers to strings and marshalled into JSON.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/webauthn/register \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"public_key_credential": "{\"type\":\"public-key\",\"id\":\"Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlY\",\"rawId\":\"Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlY\",\"response\":{\"clientDataJSON\":\"eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiaFladExOVDlTSWdacVBuS2ZiblFYM25DSjdOYXZUVF9TNm9DOVhSRVl2MEYiLCJvcmlnaW4iOiJodHRwOi8vbG9jYWxob3N0OjMwMDAiLCJjcm9zc09yaWdpbiI6ZmFsc2V9\",\"attestationObject\":\"o2NmbXRmcGFja2VkZ2F0dFN0bXSiY2FsZyZjc2lnWEYwRAIgLEvyXrb_aMCVOjpYBLpm3cPaaquDN0ouXaL27SF9Lp0CIB2f56tWUDvs6oBl3pMxIIrJqJhZKkK7btJtWVDLsFFbaGF1dGhEYXRhWP5Jlg3liA6MaHQ0Fw9kdmBbj-SuuaKGMseZXPO6gx2XY0VheZqwrc4AAjW8xgpkiwsl8fBVAwB6Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlalAQIDJiABIVggFCI-4HODPxlfeBwfFyzQG_btRm_pB6mb9E1E-rANMwoiWCBCr6C2SQOGElh9N9OMzVBcMnOolAcvz3S0STbnNTHOmg\"},\"clientExtensionResults\":{}}"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"webauthn_registration_id": "webauthn-registration-test-5c44cc6a-8af7-48d6-8da7-ea821342f5a6"
}Initiate the authentication of a WebAuthn registration. After calling this endpoint, the browser will need to call navigator.credentials.get() with the data from public_key_credential_request_options passed to the navigator.credentials.get() request via the public key argument. We recommend using the get() wrapper provided by the webauthn-json library.
If you are not using the webauthn-json library, the public_key_credential_request_options will need to be converted to a suitable public key by unmarshalling the JSON and converting some the fields to array buffers.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/webauthn/authenticate/start \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
"domain": "example.com"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"public_key_credential_request_options": "{\"allowCredentials\":[{\"id\":\"AUnfDtA+myCDdumkKnVp2Sk0MIWCPXQVL2mG3h+xQBvLEF+MmNqvj2ZwNIY8id5UHz7ogZKmGgc0mM9yYVhdJNU1n6nIwPBGUuZpr3N18trqXMKxejYYKwCO4BmSHA==\",\"type\":\"public-key\"},],\"challenge\":\"hYZtLNT9SIgZqPnKfbnQX3nCJ7NavTT_S6oC9XREYv0F\",\"rpId\":\"example.com\",\"timeout\":300000,\"userVerification\":\"discouraged\"}"
}Complete the authentication of a WebAuthn registration by passing the response from the navigator.credentials.get() request to the authenticate endpoint.
If the webauthn-json library's get() method was used, the response can be passed directly to the authenticate endpoint. If not some fields from the navigator.credentials.get() response will need to be converted from array buffers to strings and marshalled into JSON.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/webauthn/authenticate \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"public_key_credential": "{\"type\":\"public-key\",\"id\":\"Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlY\",\"rawId\":\"Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlY\",\"response\":{\"authenticatorData\":\"SZYN5YgOjGh7NBcPZHZgW1_krrmihjLHmVzzuoNcl2MFYZKokg\",\"clientDataJSON\":\"eyJ2eXBlOjopo2ViYBx0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiWEtEWDVJa25EWEU3by1KQlRkYTNfS1NiTXdmb3dMWDQxMldlNEFDY04tYWgiLCJvcmlnaW4iOiJodHRwOi8vbG9jYWxob3N0OjMwMDAiLCJjcm9zc09yaWdpbiI6ZmFsc2V9\",\"signature\":\"MEYCIQDU1FGXEBrq3hsQ2ye1pBcYLMu7zmzLVVdcbs6R21hGyAIhAJmpdBo2Hd7P4Ks9VFKBUYbKSIioMdhl2XIIjWHNKD77\",\"userHandle\":\"dXNlus1kZXZlbG9wLBC2M2E1MGI0LWEwMGEtNGU3NC89NTJmLTFlOGRhODE2nDBnMw\"},\"clientExtensionResults\":{}}"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"session": null
"session_jwt": "",
"session_token": "",
"user": {...},
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"webauthn_registration_id": "webauthn-registration-test-5c44cc6a-8af7-48d6-8da7-ea821342f5a6",
}Time-based One-time Passcodes (TOTPs) are one-time passcodes that are generated based on a shared secret and the current time. TOTPs are also often referred to as Authenticator Apps and are a common form of secondary authentication. Creating a Stytch instance of a TOTP for a User creates a shared secret. This secret is shared by Stytch with the end user's authenticator application of choice (e.g. Google Authenticator). The authenticator app can then generate TOTPs that are valid for a specific amount of time (generally 30 seconds). The end user inputs the TOTP and the developer can use the Authenticate TOTP endpoint to verify that the TOTP is valid.
Create a new TOTP instance for a user. The user can use the authenticator application of their choice to scan the QR code or enter the secret.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/totps \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"secret": "BTGNX5RKJRMQWQFRQKTG34JCF6XDRHZS",
"totp_id": "totp-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c",
"qr_code": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAAAAADYoy0BAAAG8ElEQVR...8EAAD//7dQP/5Y00bRAAAAAElFTkSuQmCC",
"recovery_codes": [
"ckss-2skx-ebow",
"spbc-424h-usy0",
"hi08-n5tk-lns5",
"1n6i-l5na-8axe",
"aduj-eufq-w6yy",
"i4l3-dxyt-urmx",
"ayyi-utb0-gj0s",
"lz0m-02bi-psbx",
"l2qm-zrk1-8ujs",
"c2qd-k7m4-ifmc"
]
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user": {...},
}Authenticate a TOTP code entered by a user.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/totps/authenticate \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"totp_code": "576831"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"totp_id": "totp-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c",
"session": null,
"session_jwt": "",
"session_token": "",
"user": {...},
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
}Retrieve the recovery codes for a TOTP instance tied to a User.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/totps/recovery_codes \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"totps": [
{
"totp_id": "totp-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c",
"verified": true,
"recovery_codes": [
"ckss-2skx-ebow",
"spbc-424h-usy0",
"hi08-n5tk-lns5",
"1n6i-l5na-8axe",
"aduj-eufq-w6yy",
"i4l3-dxyt-urmx",
"ayyi-utb0-gj0s",
"lz0m-02bi-psbx",
"l2qm-zrk1-8ujs",
"c2qd-k7m4-ifmc"
]
}
]
}Authenticate a recovery code for a TOTP instance.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/totps/recover \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"recovery_code": "ckss-2skx-ebow"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"session": null,
"session_jwt": "",
"session_token": "",
"totp_id": "totp-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c"
"user": {...},
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
}Crypto wallets allow users to hold digital assets, like cryptocurrencies and NFTs, and easily cryptographically authenticate themselves on a blockchain. Our Crypto wallets product allows your users to seamlessly authenticate to your application via MetaMask, Phantom, or any other Ethereum or Solana based crypto wallets. Unlock Web3 via Stytch without having to touch a blockchain.
Initiate the authentication of a crypto wallet. After calling this endpoint, the user will need to sign a message containing only the returned challenge field.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/crypto_wallets/authenticate/start \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"crypto_wallet_type": "ethereum",
"crypto_wallet_address": "0x6df2dB4Fb3DA35d241901Bd53367770BF03123f1"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"challenge": "Signing in with Project: 7_EPetPqfdEiDCJtgad6-xsXytN3Ee9tx6mdRTQK3fC7-J2PDxpP1GAvYB9Ic4E09h-K88STiRIzKSGP",
"user_created": true
}Complete the authentication of a crypto wallet by passing the signature.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/crypto_wallets/authenticate \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"crypto_wallet_type": "ethereum",
"crypto_wallet_address": "0x6df2dB4Fb3DA35d241901Bd53367770BF03123f1",
"signature": "0x0c4f82edc3c818b6beff4b89e0682994e5878074609903cecdfb843241728be32f75949e2fbae63dcccdef97c0e3789a26441f7e11456cc1f2ef79b3a436010f1b"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user": {...},
"session_jwt": "",
"session_token": ""
}Stytch supports creating, storing, and authenticating password based users, as well as support for account recovery (password reset) and account deduplication with passwordless login methods.
For migrating existing password based users into Stytch, we support importing bcrypt, scrypt, argon2, MD-5, and SHA-1 password hashes from common auth providers like Cognito, Auth0, and Firebase.
Our implementation of passwords has built-in breach detection powered by HaveIBeenPwned on both sign-up and login, to prevent the use of compromised credentials and uses Dropbox’s zxcvbn strength requirements to guide users towards creating passwords that are easy for humans to remember but difficult for computers to crack.
Create a new user with a password and an authenticated session for the user if requested. If a user with this email already exists in the project, this API will return an error.
Existing passwordless users who wish to create a password need to go through the reset password flow.
This endpoint will return an error if the password provided does not meet our strength requirements, which you can check beforehand with the password strength endpoint.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/passwords \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "sandbox@stytch.com",
"password": "YqMsjsHTgJ$B&Zjr"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
}Authenticate a user with their email address and password. This endpoint verifies that the user has a password currently set, and that the entered password is correct. There are two instances where the endpoint will return a reset_password error even if they enter their previous password:
One: The user’s credentials appeared in the HaveIBeenPwned dataset. We force a password reset to ensure that the user is the legitimate owner of the email address, and not a malicious actor abusing the compromised credentials.
Two: A user that has previously authenticated with email/password uses a passwordless authentication method tied to the same email address (e.g. Magic Links, Google OAuth) for the first time. Any subsequent email/password authentication attempt will result in this error. We force a password reset in this instance in order to safely deduplicate the account by email address, without introducing the risk of a pre-hijack account takeover attack.
Imagine a bad actor creates many accounts using passwords and the known email addresses of their victims. If a victim comes to the site and logs in for the first time with an email-based passwordless authentication method then both the victim and the bad actor have credentials to access to the same account. To prevent this, any further email/password login attempts first require a password reset which can only be accomplished by someone with access to the underlying email address.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/passwords/authenticate \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "sandbox@stytch.com",
"password": "YqMsjsHTgJ$B&Zjr"
}'RESPONSE
{
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"session": null,
"session_jwt": "",
"session_token": "",
"status_code": 200,
"user": {...},
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
}Initiates a password reset for the email address provided. This will trigger an email to be sent to the address, containing a magic link that will allow them to set a new password and authenticate.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/passwords/email/reset/start \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "sandbox@stytch.com"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
}Reset the user’s password and authenticate them. This endpoint checks that the magic link token is valid, hasn’t expired, or already been used – and can optionally require additional security settings, such as the IP address and user agent matching the initial reset request.
The provided password needs to meet our password strength requirements, which can be checked in advance with the password strength endpoint. If the token and password are accepted, the password is securely stored for future authentication and the user is authenticated.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/passwords/email/reset \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"token": "PvC5UudZ7TPZbELt95yXAQ-8MeEUCRob8bUQ-g52fIJs",
"password": "YqMsjsHTgJ$B&Zjr"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
}Reset the User’s password using their existing password.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/passwords/existing_password/reset \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "sandbox@stytch.com",
"existing_password": "old_password",
"new_password": "YqMsjsHTgJ$B&Zjr"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
}Reset the user’s password using their existing session. The endpoint will error if the session does not have a password, email magic link, or email OTP authentication factor that has been issued within the last 5 minutes.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/passwords/session/reset \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"password": "YqMsjsHTgJ$B&Zjr",
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"session": null
}This API allows you to check whether or not the user’s provided password is valid, and to provide feedback to the user on how to increase the strength of their password.
This endpoint adapts to your Project's password strength configuration. If you're using zxcvbn, the default, your passwords are considered valid if the strength score is >= 3. If you're using LUDS, your passwords are considered valid if they meet the requirements that you've set with Stytch. Reach out to support@stytch.com if you'd like to change your password strength configuration.
The feedback object contains relevant fields for you to relay feedback to users that failed to create a strong enough password.
If you're using zxcvbn, the feedback object will contain warning and suggestions for any password that does not meet the zxcvbn strength requirements. You can return these strings directly to the user to help them craft a strong password.
If you're using LUDS, the feedback object will contain an object named luds_requirements which contain a collection of fields that the user failed or passed. You'll want to prompt the user to create a password that meets all of the requirements that they failed.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/passwords/strength_check \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"password": "YqMsjsHTgJ$B&Zjr"
}'RESPONSE
{
"breach_detection_on_create": true,
"breached_password": false,
"feedback": {
"suggestions": null,
"warning": null,
"has_digit": true,
"has_lower_case": false,
"has_symbol": false,
"has_upper_case": false,
"missing_characters": 6,
"missing_complexity": 1
},
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"score": 0,
"status_code": 200,
"strength_policy": "luds",
"valid_password": false
}Adds an existing password to a User's email that doesn't have a password yet. We support migrating users from passwords stored with bcrypt, scrypt, argon2, MD-5, and SHA-1. This endpoint has a rate limit of 10 requests per second.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/passwords/migrate \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "sandbox@stytch.com",
"hash": "$2a$12$vefoDBbzuMb/NczV/fc9QemTizkNAZr9EO02pIUHPAAJibcYp0.ne",
"hash_type": "bcrypt"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
"user_created": true
}Learn more about Stytch concepts, data models, and general API concerns.
The Stytch API uses basic authentication for all API requests. The username will be your project_id and the password will be your secret. You can retrieve both your test and live API keys from the developer dashboard.
There are two environments, TEST and LIVE, each with unique API keys and urls, test.stytch.com and api.stytch.com. Additionally, the resources created in each environment are tied to the environment they were created in. The ids used for objects include the environment they are tried to, for example user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6.
Email templates control the subject line and body of the email a user receives. For Magic Link endpoints that send emails, there are three possible email templates a user can receive: login, signup or invite. Which email template a user receives is based on a combination of the user's state in the Stytch backend and the endpoint used.
You can use the official Stytch Postman collection to test and learn about the Stytch API before writing any code. The workspace includes requests for all of Stytch's API endpoints. Find it here!
To ensure your users are always routed to the correct place, Stytch verifies any redirect URLs provided in requests against redirect URLs that are configured in the developer dashboard. For each redirect URL type (login, signup or invite), a developer can specify one or more URLs for each type.
Each Project also has separate redirect URLs for the test and live environments. When verifying the redirect URL from the request against the predefined URLs for the project, Stytch looks for an exact match, including any subdirectories and query parameters. Please visit the Dashboard to set redirect URLs for your project.
By default, all redirect URLs are set to http://localhost:3000 for the Test environment.
Stytch Users may contain metadata - arbitrary JSON objects for recording application-specific information.
Stytch Users contain two types of metadata - trusted_metadata and untrusted_metadata.
Direct API integrations can read and write to both trusted_metadata and untrusted_metadata.
Frontend SDK integrations can read and write to untrusted_metadata, but only read trusted_metadata.
Secure fields, such as a user's role, billing_status, or stripe_customer_id should only be stored in trusted_metadata by using a direct API integration. Fields that a user can be allowed to edit directly - such as display_theme or preferred_locale may be stored in untrusted_metadata.
Do not store any sensitive information (passport numbers, credit card details, etc.) as metadata.
Metadata update payloads will be merged with the existing metadata at the top level only. Send a top-level value of null to delete an existing field. To delete all metadata from an object, send a top-level value of null for every existing field. Stytch will not merge deeply nested objects or arrays. To add a field to a deeply nested object, or update an array, replace the entire top-level key.
Initial:
{
"trusted_metadata": {
"key1": "value1"
}
}
Update:
{
"trusted_metadata": {
"key2": "value2"
}
}
Result:
{
"trusted_metadata": {
"key1": "value1",
"key2": "value2"
}
}
Initial:
{
"untrusted_metadata": {
"key1": "value1"
}
}
Update:
{
"untrusted_metadata": {
"key1": "value2"
}
}
Result:
{
"untrusted_metadata": {
"key1": "value2"
}
}
Initial:
{
"trusted_metadata": {
"key1": [{"deep": "value1"}],
"other_key": "other_value"
}
}
Update:
{
"trusted_metadata": {
"key1": [{"deep": "value1"}, {"deep": "value2"}]
}
}
Result:
{
"trusted_metadata": {
"key1": [{"deep": "value1"}, {"deep": "value2"}],
"other_key": "other_value"
}
}
Initial:
{
"untrusted_metadata": {
"key1": [{"deep": "value1"}],
"other_key": "other_value"
}
}
Update:
{
"untrusted_metadata": {
"key1": null
}
}
Result:
{
"untrusted_metadata": {
"other_key": "other_value"
}
}
Initial:
{
"trusted_metadata": {
"key1": [{"deep": "value1"}],
"other_key": "other_value"
}
}
Update:
{
"trusted_metadata": {
"key1": null,
"other_key": null
}
}
Result:
{
"trusted_metadata": {}
}
A user's state impacts how they are treated within Stytch, in particular which email template they are sent. Users within Stytch can be in three different states: pending, active, or deleted.
Stytch uses HTTP response status codes to indicate the success or failure of your API requests. For failures, Stytch returns an error using the appropriate status code. There are three categories for status codes:
4xx errors generally require some action to be taken to resolve them. Below is a list of possible error codes that can be returned, along with additional information about how to resolve them. These types of errors also include the url attribute with a direct link to the specific error code it corresponds to.
OBJECT
{
"status_code": 403,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "use_https",
"error_message": "Please use https instead of http.",
"error_url": "https://stytch.com/docs/b2b/api/errors/403/use_https"
}Cannot create a new TOTP for the specified user since the user already has an active TOTP. Users may only have one active TOTP at a time.
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "active_totp_exists",
"error_message": "Cannot create a new TOTP for the specified user since the user already has an active TOTP. Users may only have one active TOTP at a time.",
"error_url": "https://stytch.com/docs/api/errors/400/active_totp_exists"
}The Apple OAuth config was not found.
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "apple_oauth_config_not_found",
"error_message": "The Apple OAuth config was not found.",
"error_url": "https://stytch.com/docs/api/errors/400/apple_oauth_config_not_found"
}The key_length value doesn't match the length of the provided hash.
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "argon_2_key_length_mismatch",
"error_message": "The key_length value doesn't match the length of the provided hash.",
"error_url": "https://stytch.com/docs/api/errors/400/argon_2_key_length_mismatch"
}The submitted request is invalid.
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "bad_request",
"error_message": "The submitted request is invalid.",
"error_url": "https://stytch.com/docs/api/errors/400/bad_request"
}You cannot use this endpoint in the live environment until credit card details are added to your account, but you can try the endpoint in the test environment. Once your billing information is verified, this endpoint can be used in live. Your first 5,000 monthly active users are free every month, but collecting this information helps us prevent abuse of the platform. Please go to billing settings to provide billing information.
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "billing_not_verified",
"error_message": "ou cannot use this endpoint in the Live environment until credit card details are added to your account, but you can try the endpoint in the Test environment. Once your billing information is verified, this endpoint can be used in Live. Your first 5,000 monthly active users are free every month, but collecting this information helps us prevent abuse of the platform. Please go to https://stytch.com/settings/billing to provide billing information.",
"error_url": "https://stytch.com/docs/api/errors/400/billing_not_verified"
}You can only send magic links to emails matching your project's domain until credit card details are added to your account. Once your billing information is verified, emails can be sent to anyone. Your first 5,000 monthly active users are free every month, but collecting this information helps us prevent abuse of the platform. Please go to billing settings to provide billing information.
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "billing_not_verified_for_email",
"error_message": "You can only send magic links to emails matching your project's domain until credit card details are added to your account. Once your billing information is verified, emails can be sent to anyone. Your first 5,000 monthly active users are free every month, but collecting this information helps us prevent abuse of the platform. Please see https://stytch.com/settings/billing to provide billing information.",
"error_url": "https://stytch.com/docs/api/errors/400/billing_not_verified_for_email"
}Cannot delete the last email for a user with a password. This ensures they can complete a password reset.
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "cannot_delete_email",
"error_message": "Cannot delete the last email for a user with a password. This ensures they can complete a password reset.",
"error_url": "https://stytch.com/docs/api/errors/400/cannot_delete_email"
}You cannot delete the last primary factor (email, phone number, crypto wallet) for a user because that would make their account difficult or impossible to recover. If you want to remove the user from your project, delete the user instead.
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "cannot_delete_last_primary_factor",
"error_message": "Cannot delete the last primary factor (email, phone number, crypto wallet) for a user. If you want to delete the user instead, use the DeleteUser endpoint: https://stytch.com/docs/api/delete-user",
"error_url": "https://stytch.com/docs/api/errors/400/cannot_delete_last_primary_factor"
}Cannot reset user's password using their existing password. This could be because their existing password was part of a data breach or to prevent password squatting. Please reset the password via a session or email reset.
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "cannot_reset_password_with_existing_password",
"error_message": "Cannot reset user's password using their existing password. This could be because their existing password was part of a data breach or to prevent password squatting. Please reset the password via a session or email reset.",
"error_url": "https://stytch.com/docs/api/errors/400/cannot_reset_password_with_existing_password"
}Mobile biometrics can only be used for active users.
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "cannot_use_biometrics_with_pending_user",
"error_message": "Mobile biometrics can only be used for active users.",
"error_url": "https://stytch.com/docs/api/errors/400/cannot_use_biometrics_with_pending_user"
}Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "cannot_use_webauthn_with_pending_user",
"error_message": "WebAuthn can only be used for active users. To learn more about WebAuthn and user states read more at https://stytch.com/docs/api/webauthn-overview and https://stytch.com/docs/api/user-states.",
"error_url": "https://stytch.com/docs/api/errors/400/cannot_use_webauthn_with_pending_user"
}Client secret is too long. Please make sure you have the correct value.
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "client_secret_too_long",
"error_message": "Client secret is too long. Please make sure you have the correct value.",
"error_url": "https://stytch.com/docs/api/errors/400/client_secret_too_long"
}Could not parse the biometric signature. The field should be base64 encoded.
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "could_not_parse_biometric_signature",
"error_message": "Could not parse the biometric signature. The field should be base64 encoded.",
"error_url": "https://stytch.com/docs/api/errors/400/could_not_parse_biometric_signature"
}Custom claims are too large.
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "custom_claims_too_large",
"error_message": "Custom claims are too large.",
"error_url": "https://stytch.com/docs/api/errors/400/custom_claims_too_large"
}This endpoint has been deprecated
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "deprecated_endpoint",
"error_message": "This endpoint has been deprecated",
"error_url": "https://stytch.com/docs/api/errors/400/deprecated_endpoint"
}This biometric public key has already been registered. Please register a different key.
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "duplicate_biometric_registration",
"error_message": "This biometric public key has already been registered. Please register a different key.",
"error_url": "https://stytch.com/docs/api/errors/400/duplicate_biometric_registration"
}A user with the specified email already exists for this project.
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "duplicate_email",
"error_message": "A user with the specified email already exists for this project.",
"error_url": "https://stytch.com/docs/api/errors/400/duplicate_email"
}The specified email is already tied to this user.
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "duplicate_email_for_user",
"error_message": "The specified email is already tied to this user.",
"error_url": "https://stytch.com/docs/api/errors/400/duplicate_email_for_user"
}An organization with the specified name already exists.
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "duplicate_organization",
"error_message": "An organization with the specified name already exists.",
"error_url": "https://stytch.com/docs/api/errors/400/duplicate_organization"
}A user with the specified email already exists for this organization.
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "duplicate_organization_user",
"error_message": "A user with the specified email already exists for this organization.",
"error_url": "https://stytch.com/docs/api/errors/400/duplicate_organization_user"
}The phone number provided is already associated with an existing Stytch user.
You’re attempting to create a new Stytch user with a phone number that already belongs to an existing user.
Instead of creating a new user, locate the existing user via our Search users endpoint. You can search by user phone number by adding a phone_number filter to your search request.
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "duplicate_phone_number",
"error_message": "A user with the specified phone number already exists for this project.",
"error_url": "https://stytch.com/docs/api/errors/400/duplicate_phone_number"
}The specified phone number is already tied to this user.
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "duplicate_phone_number_for_user",
"error_message": "The specified phone number is already tied to this user.",
"error_url": "https://stytch.com/docs/api/errors/400/duplicate_phone_number_for_user"
}