Consumer API Reference

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.


Create User

POSThttps://test.stytch.com/v1/users

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.


Body parameters


emailstring

phone_numberstring

nameobject

trusted_metadataobject

untrusted_metadataobject

create_user_as_pendingboolean

attributesobject

Response fields


status_codeint

request_idstring

user_idstring

userobject

email_idstring

statusstring

REQUEST

Node
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

201
{
  "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 Users

POSThttps://test.stytch.com/v1/users/search

Search for Users within your Stytch Project. Submit an empty query in the request to return all Users.


Body parameters


limitint

cursorstring

queryobject

Response fields


request_idstring

status_codeint

resultsarray[objects]

results_metadataobject

REQUEST

Search
Node
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

200
{
  "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 User

GEThttps://test.stytch.com/v1/users/{user_id}

Get information about a specific User.


Path parameters


user_id*string

Response fields


status_codeint

request_idstring

user_idstring

nameobject

trusted_metadataobject

untrusted_metadataobject

emailsarray[objects]

phone_numbersarray[objects]

providersarray[objects]

webauthn_registrationsarray[objects]

biometric_registrationsarray[objects]

totpsarray[objects]

crypto_walletsarray[objects]

passwordobject

created_atstring

statusstring

REQUEST

Node
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

200
{
  "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 User

PUThttps://test.stytch.com/v1/users/{user_id}

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


user_id*string

Body parameters


nameobject

trusted_metadataobject

untrusted_metadataobject

attributesobject

Response fields


status_codeint

request_idstring

user_idstring

userobject

nameobject

emailsarray[objects]

phone_numbersarray[objects]

crypto_walletsarray[objects]

REQUEST

Node
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

200
{
  "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 User

DELETEhttps://test.stytch.com/v1/users/{user_id}

Delete a User from Stytch.


Path parameters


user_id*string

Response fields


status_codeint

request_idstring

user_idstring

REQUEST

Node
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

200
{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
}

Delete User email

DELETEhttps://test.stytch.com/v1/users/emails/{email_id}

Delete an email from a User.


Path parameters


email_id*string

Response fields


status_codeint

request_idstring

user_idstring

userobject

REQUEST

Node
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

200
{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "user": {...}
}

Delete User phone number

DELETEhttps://test.stytch.com/v1/users/phone_numbers/{phone_id}

Delete a phone number from a User.


Path parameters


phone_id*string

Response fields


status_codeint

request_idstring

user_idstring

userobject

REQUEST

Node
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

200
{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "user": {...}
}

Delete User WebAuthn registration

DELETEhttps://test.stytch.com/v1/users/webauthn_registrations/{webauthn_registration_id}

Delete a WebAuthn registration from a User.


Path parameters


webauthn_registration_id*string

Response fields


status_codeint

request_idstring

user_idstring

userobject

REQUEST

Node
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

200
{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "user": {...}
}

Delete User biometric registration

DELETEhttps://test.stytch.com/v1/users/biometric_registrations/{biometric_registration_id}

Delete a biometric registration from a User.


Path parameters


biometric_registration_id*string

Response fields


status_codeint

request_idstring

user_idstring

userobject

REQUEST

Node
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

200
{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "user", {...}
}

Delete User TOTP

DELETEhttps://test.stytch.com/v1/users/totps/{totp_id}

Delete a TOTP from a User.


Path parameters


totp_id*string

Response fields


status_codeint

request_idstring

user_idstring

userobject

REQUEST

Node
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

200
{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "user": {...}
}

Delete User crypto wallet

DELETEhttps://test.stytch.com/v1/users/crypto_wallets/{crypto_wallet_id}

Delete a crypto wallet from a User.


Path parameters


crypto_wallet_id*string

Response fields


status_codeint

request_idstring

user_idstring

userobject

REQUEST

Node
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

200
{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "user": {...}
}

Delete User password

DELETEhttps://test.stytch.com/v1/users/passwords/{password_id}

Delete a password from a User.


Path parameters


password_id*string

Response fields


status_codeint

request_idstring

user_idstring

userobject

REQUEST

Node
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

200
{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "user": {...}
}

Delete User OAuth registration

DELETEhttps://test.stytch.com/v1/users/oauth/{oauth_user_registration_id}

Delete an OAuth registration from a User.


Path parameters


oauth_user_registration_id*string

Response fields


status_codeint

request_idstring

user_idstring

userobject

REQUEST

Node
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

200
{
    "status_code": 200,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
    "user": {...}
}

Send Magic Link by email

POSThttps://test.stytch.com/v1/magic_links/email/send

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.

Add an email to an existing user

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.

Next steps

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.


Body parameters


email*string

login_magic_link_urlstring

signup_magic_link_urlstring

login_expiration_minutesint

signup_expiration_minutesint

login_template_idstring

signup_template_idstring

localestring

attributesobject

code_challengestring

user_idstring

session_tokenstring

session_jwtstring

Response fields


status_codeint

request_idstring

user_idstring

email_idstring

REQUEST

Node
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

200
{
    "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"
}

Log in or create User by email

POSThttps://test.stytch.com/v1/magic_links/email/login_or_create

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.

Next steps

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.


Body parameters


email*string

login_magic_link_urlstring

signup_magic_link_urlstring

login_expiration_minutesint

signup_expiration_minutesint

login_template_idstring

signup_template_idstring

create_user_as_pendingboolean

localestring

attributesobject

code_challengestring

Response fields


status_codeint

request_idstring

user_idstring

email_idstring

user_createdboolean

REQUEST

Node
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

200
{
  "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
}

Invite by email

POSThttps://test.stytch.com/v1/magic_links/email/invite

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.

Next steps

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.


Body parameters


email*string

invite_magic_link_urlstring

invite_expiration_minutesint

invite_template_idstring

nameobject

localestring

attributesobject

Response fields


status_codeint

request_idstring

user_idstring

email_idstring

REQUEST

Node
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

200
{
  "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 pending invite

POSThttps://test.stytch.com/v1/magic_links/email/revoke_invite

Revoke a pending invite based on the email provided.


Body parameters


email*string

Response fields


status_codeint

request_idstring

REQUEST

Node
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

200
{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141"
}




SMS one-time passcodes (OTP) overview

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 one-time passcode by SMS

POSThttps://test.stytch.com/v1/otps/sms/send

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.

Add a phone number to an existing user

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.

Next steps

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.


Body parameters


phone_number*string

expiration_minutesint

localestring

attributesobject

user_idstring

session_tokenstring

session_jwtstring

Response fields


status_codeint

request_idstring

user_idstring

phone_idstring

REQUEST

Node
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

200
{
  "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"
}

Log in or create User by SMS OTP

POSThttps://test.stytch.com/v1/otps/sms/login_or_create

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.

Next steps

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.


Body parameters


phone_number*string

expiration_minutesint

create_user_as_pendingboolean

attributesobject

Response fields


status_codeint

request_idstring

user_idstring

phone_idstring

user_createdboolean

REQUEST

Node
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

200
{
  "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 one-time passcode by WhatsApp

POSThttps://test.stytch.com/v1/otps/whatsapp/send

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.

Add a phone number to an existing user

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.

Next steps

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.


Body parameters


phone_number*string

expiration_minutesint

localestring

attributesobject

user_idstring

session_tokenstring

session_jwtstring

Response fields


status_codeint

request_idstring

user_idstring

phone_idstring

REQUEST

Node
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

200
{
  "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"
}

Log in or create User by WhatsApp OTP

POSThttps://test.stytch.com/v1/otps/whatsapp/login_or_create

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.

Next steps

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.


Body parameters


phone_number*string

expiration_minutesint

create_user_as_pendingboolean

attributesobject

Response fields


status_codeint

request_idstring

user_idstring

phone_idstring

user_createdboolean

REQUEST

Node
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

200
{
  "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 one-time passcodes (OTP) overview

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 one-time passcode by email

POSThttps://test.stytch.com/v1/magic_links/email/send

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.

Add an email to an existing user

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.

Next steps

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.


Body parameters


email*string

expiration_minutesint

login_template_idstring

signup_template_idstring

localestring

attributesobject

user_idstring

session_tokenstring

session_jwtstring

Response fields


status_codeint

request_idstring

user_idstring

email_idstring

REQUEST

Node
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

200
{
  "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"
}

Log in or create User by email

POSThttps://test.stytch.com/v1/otps/email/login_or_create

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.

Next steps

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.


Body parameters


email*string

expiration_minutesint

login_template_idstring

signup_template_idstring

localestring

create_user_as_pendingboolean

attributesobject

Response fields


status_codeint

request_idstring

user_idstring

email_idstring

REQUEST

Node
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

200
{
  "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 one-time passcode

POSThttps://test.stytch.com/v1/otps/authenticate

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.


Body parameters


method_id*string

code*string

optionsobject

attributesobject

session_custom_claimsmap<string, any>

session_duration_minutesstring

session_jwtstring

session_tokenstring

Response fields


status_codeint

request_idstring

user_idstring

email_idstring

REQUEST

Node
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

200
{
  "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 overview

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:

  1. Add the required client ID and client secret from the IdP to the Stytch developer dashboard.
  2. Embed the client side OAuth URL (i.e Google) for that IdP that the user will click.
  3. Add an endpoint in the backend that calls oauth-authenticate to finish the flow.

Attach OAuth factor

POSThttps://test.stytch.com/v1/oauth/attach

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.


Body parameters


provider*string

user_idstring

session_tokenstring

session_jwtstring

Response fields


status_codeint

request_idstring

oauth_attach_tokenstring

REQUEST

Node
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

200
{
    "status_code": 200,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "oauth_attach_token": "...",
}

Start Google OAuth flow

GEThttps://test.stytch.com/v1/public/oauth/google/start

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.

Scopes

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.

Next steps

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.


Query parameters


public_token*string

login_redirect_urlstring

signup_redirect_urlstring

custom_scopesstring

code_challengestring

oauth_attach_tokenstring

Response fields


status_codeint

request_idstring

redirect_urlstring

REQUEST

Node
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

302
{
    "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",
}

Start Amazon OAuth flow

GEThttps://test.stytch.com/v1/public/oauth/amazon/start

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.

Scopes

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.

Next steps

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.


Query parameters


public_token*string

login_redirect_urlstring

signup_redirect_urlstring

custom_scopesstring

code_challengestring

oauth_attach_tokenstring

Response fields


status_codeint

request_idstring

redirect_urlstring

REQUEST

Node
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

302
{
    "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",
}

Start Apple OAuth flow

GEThttps://test.stytch.com/v1/public/oauth/apple/start

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.

Scopes

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.

Next steps

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.


Query parameters


public_token*string

login_redirect_urlstring

signup_redirect_urlstring

custom_scopesstring

code_challengestring

oauth_attach_tokenstring

Response fields


status_codeint

request_idstring

redirect_urlstring

REQUEST

Node
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

302
{
    "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",
}

Start Bitbucket OAuth flow

GEThttps://test.stytch.com/v1/public/oauth/bitbucket/start

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.

Scopes

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.

Next steps

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.


Query parameters


public_token*string

login_redirect_urlstring

signup_redirect_urlstring

custom_scopesstring

code_challengestring

oauth_attach_tokenstring

Response fields


status_codeint

request_idstring

redirect_urlstring

REQUEST

Node
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

302
{
    "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",
}

Start Coinbase OAuth flow

GEThttps://test.stytch.com/v1/public/oauth/coinbase/start

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.

Scopes

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.

Next steps

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.


Query parameters


public_token*string

login_redirect_urlstring

signup_redirect_urlstring

custom_scopesstring

code_challengestring

oauth_attach_tokenstring

Response fields


status_codeint

request_idstring

redirect_urlstring

REQUEST

Node
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

302
{
    "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",
}

Start Discord OAuth flow

GEThttps://test.stytch.com/v1/public/oauth/discord/start

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.

Scopes

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.

Next steps

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.


Query parameters


public_token*string

login_redirect_urlstring

signup_redirect_urlstring

custom_scopesstring

code_challengestring

oauth_attach_tokenstring

Response fields


status_codeint

request_idstring

redirect_urlstring

REQUEST

Node
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

302
{
    "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",
}

Start Facebook OAuth flow

GEThttps://test.stytch.com/v1/public/oauth/facebook/start

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.

Scopes

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.

Next steps

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.


Query parameters


public_token*string

login_redirect_urlstring

signup_redirect_urlstring

custom_scopesstring

code_challengestring

oauth_attach_tokenstring

Response fields


status_codeint

request_idstring

redirect_urlstring

REQUEST

Node
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

302
{
    "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",
}

Start Figma OAuth flow

GEThttps://test.stytch.com/v1/public/oauth/figma/start

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.

Scopes

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.

Next steps

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.


Query parameters


public_token*string

login_redirect_urlstring

signup_redirect_urlstring

custom_scopesstring

code_challengestring

oauth_attach_tokenstring

Response fields


status_codeint

request_idstring

redirect_urlstring

REQUEST

Node
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

302
{
    "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",
}

Start Github OAuth flow

GEThttps://test.stytch.com/v1/public/oauth/github/start

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.

Scopes

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.

Next steps

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.


Query parameters


public_token*string

login_redirect_urlstring

signup_redirect_urlstring

custom_scopesstring

code_challengestring

oauth_attach_tokenstring

Response fields


status_codeint

request_idstring

redirect_urlstring

REQUEST

Node
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

302
{
    "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",
}

Start Gitlab OAuth flow

GEThttps://test.stytch.com/v1/public/oauth/gitlab/start

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.

Scopes

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.

Next steps

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.


Query parameters


public_token*string

login_redirect_urlstring

signup_redirect_urlstring

custom_scopesstring

code_challengestring

oauth_attach_tokenstring

Response fields


status_codeint

request_idstring

redirect_urlstring

REQUEST

Node
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

302
{
    "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",
}

Start Linkedin OAuth flow

GEThttps://test.stytch.com/v1/public/oauth/linkedin/start

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.

Scopes

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.

Next steps

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.


Query parameters


public_token*string

login_redirect_urlstring

signup_redirect_urlstring

custom_scopesstring

code_challengestring

oauth_attach_tokenstring

Response fields


status_codeint

request_idstring

redirect_urlstring

REQUEST

Node
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

302
{
    "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",
}

Start Microsoft OAuth flow

GEThttps://test.stytch.com/v1/public/oauth/microsoft/start

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.

Scopes

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.

Next steps

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.


Query parameters


public_token*string

login_redirect_urlstring

signup_redirect_urlstring

custom_scopesstring

code_challengestring

oauth_attach_tokenstring

Response fields


status_codeint

request_idstring

redirect_urlstring

REQUEST

Node
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

302
{
    "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",
}

Start Salesforce OAuth flow

GEThttps://test.stytch.com/v1/public/oauth/salesforce/start

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.

Scopes

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.

Next steps

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.


Query parameters


public_token*string

login_redirect_urlstring

signup_redirect_urlstring

custom_scopesstring

code_challengestring

oauth_attach_tokenstring

Response fields


status_codeint

request_idstring

redirect_urlstring

REQUEST

Node
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

302
{
    "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",
}

Start Slack OAuth flow

GEThttps://test.stytch.com/v1/public/oauth/slack/start

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.

Scopes

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.

Next steps

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.


Query parameters


public_token*string

login_redirect_urlstring

signup_redirect_urlstring

custom_scopesstring

code_challengestring

oauth_attach_tokenstring

Response fields


status_codeint

request_idstring

redirect_urlstring

REQUEST

Node
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

302
{
    "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",
}

Start Snapchat OAuth flow

GEThttps://test.stytch.com/v1/public/oauth/snapchat/start

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.

Scopes

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.

Next steps

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.


Query parameters


public_token*string

login_redirect_urlstring

signup_redirect_urlstring

custom_scopesstring

code_challengestring

oauth_attach_tokenstring

Response fields


status_codeint

request_idstring

redirect_urlstring

REQUEST

Node
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

302
{
    "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",
}

Start Tiktok OAuth flow

GEThttps://test.stytch.com/v1/public/oauth/tiktok/start

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.

Scopes

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.

Next steps

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.


Query parameters


public_token*string

login_redirect_urlstring

signup_redirect_urlstring

custom_scopesstring

code_challengestring

oauth_attach_tokenstring

Response fields


status_codeint

request_idstring

redirect_urlstring

REQUEST

Node
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

302
{
    "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",
}

Start Twitch OAuth flow

GEThttps://test.stytch.com/v1/public/oauth/twitch/start

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.

Scopes

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.

Next steps

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.


Query parameters


public_token*string

login_redirect_urlstring

signup_redirect_urlstring

custom_scopesstring

code_challengestring

oauth_attach_tokenstring

Response fields


status_codeint

request_idstring

redirect_urlstring

REQUEST

Node
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

302
{
    "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",
}

Start Twitter OAuth flow

GEThttps://test.stytch.com/v1/public/oauth/twitter/start

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.

Scopes

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.

Next steps

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.


Query parameters


public_token*string

login_redirect_urlstring

signup_redirect_urlstring

custom_scopesstring

code_challengestring

oauth_attach_tokenstring

Response fields


status_codeint

request_idstring

redirect_urlstring

REQUEST

Node
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

302
{
    "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 OAuth

POSThttps://test.stytch.com/v1/oauth/authenticate

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.


Body parameters


token*string

session_custom_claimsmap<string, any>

session_duration_minutesstring

session_jwtstring

session_tokenstring

code_verifierstring

Response fields


status_codeint

request_idstring

user_idstring

userobject

oauth_user_registration_idstring

provider_subjectstring

provider_typestring

provider_valuesobject

reset_sessionsboolean

sessionobject

session_tokenstring

session_jwtstring

REQUEST

Node
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

200
{
    "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"
}

Sessions overview

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 JWKS

GEThttps://test.stytch.com/v1/sessions/jwks/{project_id}

Get the JSON Web Key Set (JWKS) for a Stytch Project.


Path parameters


project_id*string

Response fields


status_codeint

keysarray[objects]

REQUEST

Node
curl --request GET \
      --url https://test.stytch.com/v1/sessions/jwks/PROJECT_ID

RESPONSE

200
{
    "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",
        },
    ],
}

Get Sessions

GEThttps://test.stytch.com/v1/sessions

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.


Query parameters


user_id*string

Response fields


status_codeint

request_idstring

sessionsarray[objects]

REQUEST

Node
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

200
{
  "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 Session

POSThttps://test.stytch.com/v1/sessions/authenticate

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.


Body parameters


session_custom_claimsmap<string, any>

session_duration_minutesstring

session_jwtstring

session_tokenstring

Response fields


status_codeint

request_idstring

sessionobject

session_jwtstring

session_tokenstring

userobject

REQUEST

Authenticate Session
Node
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

200
{
  "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 Session

POSThttps://test.stytch.com/v1/sessions/revoke

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.


Body parameters


session_idstring

session_jwtstring

session_tokenstring

Response fields


status_codeint

request_idstring

REQUEST

Node
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

200
{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141"
}

WebAuthn overview

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.


Start WebAuthn registration

POSThttps://test.stytch.com/v1/webauthn/register/start

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.


Body parameters


user_id*string

domain*string

user_agentstring

authenticator_typestring

Response fields


status_codeint

request_idstring

user_idstring

public_key_credential_creation_optionsstring

REQUEST

Node
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

200
{
  "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\"}"
}

Register WebAuthn

POSThttps://test.stytch.com/v1/webauthn/register

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.


Body parameters


user_id*string

public_key_credential*json

Response fields


status_codeint

request_idstring

user_idstring

webauthn_registration_idstring

REQUEST

Node
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

200
{
  "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"
}

Start WebAuthn authentication

POSThttps://test.stytch.com/v1/webauthn/authenticate/start

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.


Body parameters


user_id*string

domain*string

Response fields


status_codeint

request_idstring

user_idstring

public_key_credential_request_optionsstring

REQUEST

Node
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

200
{
  "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\"}"
}

Authenticate WebAuthn

POSThttps://test.stytch.com/v1/webauthn/authenticate

Body parameters


public_key_credential*json

session_custom_claimsmap<string, any>

session_duration_minutesstring

session_jwtstring

session_tokenstring

Response fields


status_codeint

request_idstring

sessionobject

session_jwtstring

session_tokenstring

userobject

user_idstring

webauthn_registration_idstring

REQUEST

Node
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

200
{
  "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",
}

TOTPs overview

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 TOTP

POSThttps://test.stytch.com/v1/totps

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.


Body parameters


user_id*string

expiration_minutesint

Response fields


status_codeint

request_idstring

user_idstring

userobject

secretstring

totp_idstring

qr_codestring

recovery_codesarray[strings]

REQUEST

Node
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

200
{
  "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 TOTP

POSThttps://test.stytch.com/v1/totps/authenticate

Authenticate a TOTP code entered by a user.


Body parameters


user_id*string

totp_code*string

session_custom_claimsmap<string, any>

session_duration_minutesstring

session_jwtstring

session_tokenstring

Response fields


status_codeint

request_idstring

sessionobject

session_jwtstring

session_tokenstring

userobject

user_idstring

REQUEST

Node
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

200
{
  "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"
}

Get TOTP recovery codes

POSThttps://test.stytch.com/v1/totps/recovery_codes

Retrieve the recovery codes for a TOTP instance tied to a User.


Body parameters


user_id*string

Response fields


status_codeint

request_idstring

user_idstring

totpsarray[objects]

REQUEST

Node
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

200
{
  "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"
      ]
    }
  ]
}

Recover TOTP

POSThttps://test.stytch.com/v1/totps/recover

Authenticate a recovery code for a TOTP instance.


Body parameters


user_id*string

recovery_code*string

session_custom_claimsmap<string, any>

session_duration_minutesstring

session_jwtstring

session_tokenstring

Response fields


status_codeint

request_idstring

sessionobject

session_jwtstring

session_tokenstring

totp_idstring

userobject

user_idstring

REQUEST

Node
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

200
{
  "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 overview

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.


Start Crypto Wallet authentication

POSThttps://test.stytch.com/v1/crypto_wallets/authenticate/start

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.


Body parameters


crypto_wallet_type*string

crypto_wallet_address*string

user_idstring

session_tokenstring

session_jwtstring

Response fields


status_codeint

request_idstring

user_idstring

challengestring

user_createdboolean

REQUEST

Node
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

200
{
  "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
}

Authenticate Crypto Wallet

POSThttps://test.stytch.com/v1/crypto_wallets/authenticate

Complete the authentication of a crypto wallet by passing the signature.


Body parameters


crypto_wallet_type*string

crypto_wallet_address*string

signature*string

session_custom_claimsmap<string, any>

session_duration_minutesstring

session_jwtstring

session_tokenstring

Response fields


status_codeint

request_idstring

user_idstring

userobject

session_jwtstring

session_tokenstring

REQUEST

Node
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

200
{
  "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": ""
}

Passwords overview

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 User with Password

POSThttps://test.stytch.com/v1/passwords

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.


Body parameters


email*string

password*string

nameobject

session_custom_claimsmap<string, any>

session_duration_minutesstring

trusted_metadataobject

untrusted_metadataobject

Response fields


status_codeint

request_idstring

user_idstring

email_idstring

REQUEST

Node
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": "MgOWGZSR$kRSkQ#X"
	}'

RESPONSE

200
{
  "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 Password

POSThttps://test.stytch.com/v1/passwords/authenticate

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.


Body parameters


email*string

password*string

session_custom_claimsmap<string, any>

session_duration_minutesstring

session_jwtstring

session_tokenstring

Response fields


status_codeint

request_idstring

sessionobject

session_jwtstring

session_tokenstring

userobject

user_idstring

REQUEST

Node
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": "MgOWGZSR$kRSkQ#X"
	}'

RESPONSE

200
{
  "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",
}

Start Password reset by email

POSThttps://test.stytch.com/v1/passwords/email/reset/start

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.


Body parameters


email*string

reset_password_redirect_urlstring

login_redirect_urlstring

reset_password_expiration_minutesint

reset_password_template_idstring

localestring

attributesobject

code_challengestring

Response fields


status_codeint

request_idstring

user_idstring

email_idstring

REQUEST

Node
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

200
{
  "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"
}

Password reset by email

POSThttps://test.stytch.com/v1/passwords/email/reset

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.


Body parameters


token*string

password*string

optionsobject

attributesobject

session_custom_claimsmap<string, any>

session_duration_minutesstring

session_jwtstring

session_tokenstring

code_verifierstring

Response fields


status_codeint

request_idstring

user_idstring

REQUEST

Node
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": "MgOWGZSR$kRSkQ#X"
	}'

RESPONSE

200
{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
}

Password reset by existing Password

POSThttps://test.stytch.com/v1/passwords/existing_password/reset

Reset the User’s password using their existing password.


Body parameters


email*string

existing_password*string

new_password*string

session_custom_claimsmap<string, any>

session_duration_minutesstring

session_jwtstring

session_tokenstring

Response fields


status_codeint

request_idstring

user_idstring

REQUEST

Node
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": "MgOWGZSR$kRSkQ#X"
	}'

RESPONSE

200
{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
}

Password reset by existing Session

POSThttps://test.stytch.com/v1/passwords/session/reset

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.


Body parameters


password*string

session_jwt*string

session_token*string

Response fields


status_codeint

request_idstring

user_idstring

sessionobject

REQUEST

Node
curl --request POST \
	--url https://test.stytch.com/v1/passwords/session/reset \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "password": "MgOWGZSR$kRSkQ#X",
	    "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q"
	}'

RESPONSE

200
{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "session": null
}

Strength check

POSThttps://test.stytch.com/v1/passwords/strength_check

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.

Password feedback

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.


Body parameters


password*string

emailstring

Response fields


status_codeint

request_idstring

breach_detection_on_createboolean

breached_passwordboolean

feedbackobject

scoreint

strength_policystring

valid_passwordboolean

REQUEST

Node
curl --request POST \
	--url https://test.stytch.com/v1/passwords/strength_check \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "password": "MgOWGZSR$kRSkQ#X"
	}'

RESPONSE

200 - LUDS invalid
{
	"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
}

Migrate Password

POSThttps://test.stytch.com/v1/passwords/migrate

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.


Body parameters


email*string

nameobject

trusted_metadataobject

untrusted_metadataobject

hash*string

hash_type*string

scrypt_configobject

argon_2_configobject

md_5_configobject

sha_1_configobject

Response fields


status_codeint

request_idstring

user_idstring

email_idstring

user_createdboolean

REQUEST

Node
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

200
{
  "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
}

Resources

Learn more about Stytch concepts, data models, and general API concerns.

Authentication

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.

Environments

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

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.

Postman collection

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!

URL validation

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.

Metadata

Stytch Users may contain metadata - arbitrary JSON objects for recording application-specific information.

Metadata restrictions

  • Metadata objects may contain a maximum of 20 top-level keys.
  • Metadata objects cannot exceed 4KB in size

Metadata permissions

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 behavior

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.

Example: adding a new field

Initial:

{
  "trusted_metadata": {
    "key1": "value1"
  }
}

Update:

{
  "trusted_metadata": {
    "key2": "value2"
  }
}

Result:

{
  "trusted_metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}

Example: replacing an existing field

Initial:

{
  "untrusted_metadata": {
    "key1": "value1"
  }
}

Update:

{
  "untrusted_metadata": {
    "key1": "value2"
  }
}

Result:

{
  "untrusted_metadata": {
    "key1": "value2"
  }
}

Example: updating a deeply nested field

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"
  }
}

Example: deleting a field

Initial:

{
  "untrusted_metadata": {
    "key1": [{"deep": "value1"}],
    "other_key": "other_value"
  }
}

Update:

{
  "untrusted_metadata": {
    "key1": null
  }
}

Result:

{
  "untrusted_metadata": {
    "other_key": "other_value"
  }
}

Example: deleting all fields

Initial:

{
  "trusted_metadata": {
    "key1": [{"deep": "value1"}],
    "other_key": "other_value"
  }
}

Update:

{
  "trusted_metadata": {
    "key1": null,
    "other_key": null
  }
}

Result:

{
  "trusted_metadata": {}
}

User states

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.

  • Active: Most users within Stytch will be in the "active" state. When a user is active and they are sent a magic link they will receive a login email template and be routed to the login_magic_link_url or magic_link_url provided in the request.
  • Pending: Stytch users are created as pending when created via the InviteByEmail endpoint or with endpoints where the create_user_as_pending flag is set to true. Once a user successfully authenticates either a magic link or an OTP code, they are marked as active within the Stytch backend. When inviting a user via the InviteByEmail endpoint the user will receive an email that uses the invite email template. Pending users who receive magic links via the other magic link endpoints will receive an email with the signup email template. Once a user successfully authenticates a magic link from either an invite or signup magic link email, they will be marked as active.
  • Deleted: Stytch users are marked as deleted when they are deleted via the DeleteUser endpoint. Once a user is deleted, any phone numbers or emails tied to that user are also deleted. You will be unable to send that user magic links or OTP codes.

Errors overview

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:

  • 2xx success status codes confirm that your request worked as expected.
  • 4xx error status codes indicate an error because of the information provided (e.g., a required parameter was omitted).
  • 5xx error status codes are rare and indicate an error with Stytch’s servers.

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.


Error object


Fields


status_codeint

request_idstring

error_typestring

error_messagestring

error_url string

OBJECT

403
{
  "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"
}

400 errors

active_totp_exists

400Bad request

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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

apple_oauth_config_not_found

400Bad request

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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

argon_2_key_length_mismatch

400Bad request

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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

bad_request

400Bad request

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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

billing_not_verified

400Bad 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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

billing_not_verified_for_email

400Bad request

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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

cannot_delete_email

400Bad request

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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

cannot_delete_last_primary_factor

400Bad request

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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

cannot_reset_password_with_existing_password

400Bad request

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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

cannot_use_biometrics_with_pending_user

400Bad request

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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

cannot_use_webauthn_with_pending_user

400Bad request

WebAuthn can only be used with active users. To learn more about WebAuthn and user states please see here and here.

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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

client_secret_too_long

400Bad request

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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

could_not_parse_biometric_signature

400Bad request

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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

custom_claims_too_large

400Bad request

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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

deprecated_endpoint

400Bad request

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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

duplicate_biometric_registration

400Bad request

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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

duplicate_email

400Bad request

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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

duplicate_email_for_user

400Bad request

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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

duplicate_organization

400Bad request

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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

duplicate_organization_user

400Bad request

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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

duplicate_phone_number

400Bad request

The phone number provided is already associated with an existing Stytch user.

Common causes

  • You’re attempting to create a new Stytch user with a phone number that already belongs to an existing user.

Troubleshooting steps

  • 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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

duplicate_phone_number_for_user

400Bad request

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"
}
How to get help
Visit our forum
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack

duplicate_project_user

400Bad request

A project user