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

email string

The email to use for email magic links.

phone_number string

The phone number to use for one-time passcodes. The phone number should be in E.164 format.

name object

The name of the user. Each field in the name object is optional.

Collapse

first_name string

The first name of the user.

middle_name string

The middle name(s) of the user.

last_name string

The last name of the user.

trusted_metadata object

The trusted_metadata field contains an arbitrary JSON object of application-specific data. See the Metadata reference for complete field behavior details.

untrusted_metadata object

The untrusted_metadata field contains an arbitrary JSON object of application-specific data. Untrusted metadata can be edited by end users directly via the SDK, and cannot be used to store critical information. See the Metadata reference for complete field behavior details.

create_user_as_pending boolean

Flag for whether or not to save a user as pending vs active in Stytch. Defaults to false. If true, users will be saved with status pending in Stytch's backend until authenticated. If false, users will be created as active. An example usage of a true flag would be to require users to verify their phone by entering the OTP code before creating an account for them.

attributes object

Provided attributes help with fraud detection.

Collapse

ip_address string

The IP address of the user.

user_agent string

The user agent of the user.

Response fields

status_code int

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.

request_id string

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.

user_id string

Globally unique UUID that identifies a specific user in the Stytch API. The user_id critical to perform operations on a user in our API, like Get user, Delete user, etc, so be sure to preserve this value.

user object

The user object affected by this API call. See the Get user endpoint for complete response field details.

email_id string

Globally unique UUID that identifies a specific email address in the Stytch API. The email_id is used when you need to operate on a specific user's email address, e.g. to delete the email address from the Stytch user.

status string

The status value denotes whether or not a user has successfully logged in at least once with any available login method.

Possible values are active and pending.

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/users \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"email": "sandbox@stytch.com"
	}'

RESPONSE

{
  "status_code": 201,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "user": {...},
  "email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
  "phone_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
  "status": "active"
}

Search users

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

Search across your users at Stytch. This endpoint also allows you to return all of your users; simply send an empty body and no filtering will be applied.

Body parameters

limit number

The number of users to return per page, the default is 100. A maximum of 1000 users can be returned by a single request. If the total size of your result is greater than one page size, you must paginate the response. See the cursor field below.

cursor string

The cursor field allows you to paginate through your result responses. Each result array is limited to 1000 users, if your query returns more than 1000 users, you will need to paginate the responses using the cursor. If you receive a response that includes a non-null next_cursor in the results_metadata object, you should repeat the call, being sure to include all of the original fields, but pass in the next_cursor in the cursor field. Continue to make calls until the next_cursor in the response is null.

Note: Our Backend SDKs have convenient helper functions to paginate for you.

query object

The optional query object contains the operator, e.g. AND or OR, and the operands that will filter your users. Only an operator is required, if you include no operands, no filtering will be applied. Similarly if you include no query object, no filtering is applied and we'll return all of your users with no filtering applied.

Collapse

operator string

The operator determines whether the operands that you supply must all be true, AND, or any users matching any operands will be returned, OR. Allowable values are "AND" or "OR".

operands array[objects]

The operands array contains all of the filters that you'd like to apply to your search. Each operand object contains a filter_name, e.g. created_at_between, and the filter_value(s).

Collapse

created_at_between object

The created_at_between filter allows you to search across your users and return only those that were created between your supplied greater_than and less_than timestamps. The filter_value accepts an object of your greater_than and less_than timestamps. All timestamps in our API conform to the RFC 3339 standard and are expressed in UTC, e.g. 2021-12-29T12:33:09Z.

Collapse

greater_than string

The greater_than timestamp specifies the beginning time for this filter, only users created after this timestamp will be returned.

less_than string

The less_than timestamp specifies the end of this filter, only users created before this timestamp will be returned.

created_at_greater_than string

Only users created after the supplied created_at_greater_than timestamp will be returned. All timestamps in our API conform to the RFC 3339 standard and are expressed in UTC, e.g. 2021-12-29T12:33:09Z.

created_at_less_than string

The created_at_less_than timestamp specifies the end of this filter, only users created before this timestamp will be returned. All timestamps in our API conform to the RFC 3339 standard and are expressed in UTC, e.g. 2021-12-29T12:33:09Z.

user_id array[strings]

The user_id filter allows you to search for one or more exact user_ids. The filter_value accepts an array of user_ids, e.g. ["user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"].

full_name_fuzzy string

The full_name_fuzzy filter allows you to search for a partial or full name match, e.g. you would like to return all Stytch users who have a name that contains "Grace" as a substring.

We filter in two ways to provide the most flexibility. First we apply your search across the combined first_name, middle_name, and last_name fields on the Users object, so any search will match if it is a substring of any part of a user's name. We also run your search across a concatenated first_name and last_name so that a search like "Grace H" will match on a user named Grace Hopper.

status string

The status filter allows you to filter your users based on their status, i.e. "active" or "pending", see create_user_as_pending for more context. The filter_value accepts "active" or "pending".

phone_number array[strings]

The phone_number filter allows you to search for one or more exact phone numbers. The filter_value accepts an array of phone number strings, e.g. ["+12025550162"].
Note: Phone numbers in the Stytch API must be valid E.164 phone numbers, i.e. +1XXXXXXXXXX, a sample regexp that you may use is ^+[1-9]d{1,14}$.

phone_number_fuzzy string

The phone_number_fuzzy filter allows you to search for a partial phone number match, e.g. you would like to return all Stytch users who have a phone number that contains "415" as a substring.

phone_id array[strings]

The phone_id filter allows you to search for one or more exact phone_ids. The filter_value accepts an array of phone_ids, e.g. ["phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0"].

phone_verified boolean

The phone_verified filter allows you to filter your users based on whether they have a verified phone number or not, i.e. has the phone number been used to successfully authenticate via Stytch.

email_address array[strings]

The email_address filter allows you to search for one or more exact email addresses. The filter_value accepts an array of email address strings, e.g. ["ghoppper@stytch.com"].

email_address_fuzzy string

The email_address_fuzzy filter allows you to search for a partial email address match, e.g. you would like to return all Stytch users who have an email address that contains "gmail" as a substring.

email_id array[strings]

The email_id filter allows you to search for one or more exact email_ids. The filter_value accepts an array of email_ids, e.g. ["email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"].

email_verified boolean

The email_verified filter allows you to filter your users based on whether they have a verified email address or not, i.e. has the email address been used to successfully authenticate via Stytch.

oauth_provider array[strings]

The oauth_provider filter allows you to filter your users based on which OAuth provider they have authenticated with, e.g. ["Google", "Apple"].

webauthn_registration_id array[strings]

The webauthn_registration_id filter allows you to search for one or more exact webauthn_registration_ids. The filter_value accepts an array of webauthn_registration_ids, e.g. ["webauthn-registration-test-5c44cc6a-8af7-48d6-8da7-ea821342f5a6"].

webauthn_registration_verified boolean

The webauthn_registration_verified filter allows you to filter your users based on whether they have a verified webauthn_registration_id or not, i.e. has the user successfully registered a WebAuthn device via Stytch.

biometric_registration_id array[strings]

The biometric_registration_id filter allows you to search for one or more exact biometric_registration_ids. The filter_value accepts an array of biometric_registration_ids, e.g. ["biometric-registration-test-6966a6fc-5264-46ee-9ba4-98c6322a5134"].

biometric_registration_verified boolean

The biometric_registration_verified filter allows you to filter your users based on whether they have a verified biometric_registration_id or not, i.e. has the user successfully registered their biometrics via Stytch.

totp_id array[strings]

The totp_id filter allows you to search for one or more exact totp_ids. The filter_value accepts an array of totp_ids, e.g. ["totp-test-81bf03a8-86e1-4d95-bd44-bb3495224953"].

totp_verified boolean

The totp_verified filter allows you to filter your users based on whether they have a verified TOTP or not, i.e. has the TOTP been used to successfully authenticate via Stytch.

crypto_wallet_id array[strings]

The crypto_wallet_id filter allows you to search for one or more exact crypto_wallet_ids. The filter_value accepts an array of crypto_wallet_ids, e.g. ["crypto-wallet-test-81bf03a8-86e1-4d95-bd44-bb3495224953"].

crypto_wallet_address array[strings]

The crypto_wallet_address filter allows you to search for one or more exact crypto wallet addresses. The filter_value accepts an array of crypto wallet address strings, e.g. ["0x6df2dB4Fb3DA35d241901Bd53367770BF03123f1"].

crypto_wallet_verified boolean

The crypto_wallet_verified filter allows you to filter your users based on whether they have a verified crypto wallet or not, i.e. has the crypto wallet been used to successfully authenticate via Stytch.

password_exists boolean

The password_exists filter allows you to filter your users based on whether they have a password or not.

Response fields

request_id string

results array

The User searchresults array contains a list of all of the user objects that match your query.

Collapse

results array

The results array contains User objects, see the Get user endpoint for complete response field detail.

results_metadata object

The User searchresults_metadata object contains metadata relevant to your specific query like total and next_cursor.

Collapse

next_cursor string

The next_cursor string is returned when your search result contains more than one page of results. This value is passed into your next /users/search call in the cursor field.

total int

The total number of users returned by your query.

status_code int

REQUEST

curl --request POST \
      --url https://test.stytch.com/v1/users/search \
      -u 'PROJECT_ID:SECRET' \
      -H 'Content-Type: application/json' \
      -d '{
          "limit": 200,
          "cursor": "",
          "query": {
            "operator": "AND",
            "operands": [
              {
                "filter_name": "phone_number",
                "filter_value": ["+12025550162"]
              },
            ]
          }
      }'

RESPONSE

{
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "results": [
    {
      "created_at": "2021-12-17T04:02:28Z",
      "crypto_wallets": [],
      "emails": [
        {
          "email": "ghopper@stytch.com",
          "email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
          "verified": false
        }
      ],
      "name": {
        "first_name": "Grace",
        "last_name": "Hopper",
        "middle_name": ""
      },
      "phone_numbers": [
        {
          "phone_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
          "phone_number": "+12025550162",
          "verified": true
        }
      ],
      "providers": [],
      "status": "active",
      "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
      "webauthn_registrations": []
    },
    { ...more users... }
  ],
  "results_metadata": {
    "next_cursor": "eyJ2IjoxLCJsIjo0NjkzfQ==",
    "total": 433
  },
  "status_code": 200
}

Get user

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

Fetch a given user to see what their various attributes are. All timestamps are formatted according to the RFC 3339 standard and are expressed in UTC, e.g. 2021-12-29T12:33:09Z.

Path parameters

user_id* string

The user_id for the user to fetch.

Response fields

status_code int

request_id string

user_id string

name object

The name object contains three values: first_name,middle_name,last_name.

trusted_metadata object

The trusted_metadata field contains an arbitrary JSON object of application-specific data. See the Metadata reference for complete field behavior details.

untrusted_metadata object

emails object

The emails object contains an array of email objects for the user.

Collapse

email_id string

email string

The email address.

verified boolean

The verified boolean denotes whether or not this send method, e.g. phone number, email address etc, has been successfully authenticated by the user.

phone_numbers object

The phone_numbers array contains an array of phone number objects for the user.

Collapse

phone_id string

Globally unique UUID that identifies a specific phone number in the Stytch API. The phone_id is used when you need to operate on a specific user's phone number, e.g. to delete the phone number from the Stytch user.

phone_number string

A phone number.

verified boolean

The verified boolean denotes whether or not this send method, e.g. phone number, email address etc, has been successfully authenticated by the user.

providers array

The providers array contains an array of provider objects for the user, i.e. which OAuth providers the user has used to link their account.

Collapse

oauth_user_registration_id string

Globally unique UUID that identifies singluar registration of a user with an OAuth identity provider in the Stytch API.

provider_subject string

The provider_subject field is the unique identifier used to identify the user within a given OAuth provider. Also commonly called the "sub" or "Subject field" in OAuth protocols.

provider_type string

The type field denotes the OAuth identity provider that the user has authenticated with, e.g. Google, Facebook, GitHub etc.

profile_picture_url string

If available, the profile_picture_url is a url of the user's profile picture set in OAuth identity the provider that the user has authenticated with, e.g. Facebook profile picture.

locale string

If available, the locale is the user's locale set in the OAuth identity provider that the user has authenticated with.

webauthn_registrations array

The webauthn_registrations array contains a list of all WebAuthn registrations for a given user in the Stytch API.

Collapse

webauthn_registration_id string

Globally unique UUID that identifies a specific WebAuthn registration in the Stytch API. The webauthn_registration_id is used when you need to operate on a specific user's WebAuthn registration, e.g. to delete the WebAuthn instance from the Stytch user.

domain string

The domain on which a WebAuthn registration was started. This will be the domain of your app.

user_agent string

The user_agent of the user's browser or device.

authenticator_type string

The authenticator_type string displays the requested authenticator type of the WebAuthn device. The two valid types are "platform" and "cross-platform". If no value is present, the WebAuthn device was created without an authenticator type preference.

verified boolean

The verified boolean denotes whether or not this send method, e.g. phone number, email address etc, has been successfully authenticated by the user.

biometric_registrations array

The biometric_registrations array contains a list of all biometric registrations for a given user in the Stytch API.

Collapse

biometric_registration_id string

Globally unique UUID that identifies a specific biometric registration in the Stytch API. The biometric_registration_id is used when you need to operate on a specific user's biometric registration, e.g. to delete the biometric registration from the Stytch user.

verified boolean

The verified boolean denotes whether or not this send method, e.g. phone number, email address etc, has been successfully authenticated by the user.

totps array

The totps array contains a list of all TOTP instances for a given user in the Stytch API.

Collapse

totp_id string

Globally unique UUID that identifies a specific TOTP instance in the Stytch API. The totp_id is used when you need to operate on a specific user's TOTP instance, e.g. to delete the TOTP instance from the Stytch user.

verified boolean

The verified boolean denotes whether or not this send method, e.g. phone number, email address etc, has been successfully authenticated by the user.

crypto_wallets array

The crypto_wallets array contains a list of all crypto wallets that a user has linked via Stytch.

Collapse

crypto_wallet_id string

Globally unique UUID that identifies a specific crypto wallet in the Stytch API. The crypto_wallet_id is used when you need to operate on a specific user's crypto wallet, e.g. to remove the crypto wallet from the Stytch user.

crypto_wallet_address string

The crypto_wallet_address is the actual blockchain address of this user's crypto wallet.

crypto_wallet_type string

The crypto_wallet_type is the blockchain that the user's crypto wallet operates on, e.g. Ethereum, Solana, etc.

verified boolean

The verified boolean denotes whether or not this send method, e.g. phone number, email address etc, has been successfully authenticated by the user.

password object

The password object is returned for users with a password. It contains thepassword_id and a requires_reset field indicating if the password requires a password reset.

created_at string

The timestamp of the user's creation. Values conform to the RFC 3339 standard and are expressed in UTC, e.g. 2021-12-29T12:33:09Z.

status string

The status value denotes whether or not a user has successfully logged in at least once with any available login method.

Possible values are active and pending.

REQUEST

curl --request GET \
	--url https://test.stytch.com/v1/users/user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6 \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "name": {
    "first_name": "Jane",
    "middle_name": "",
    "last_name": "Doe"
  },
  "trusted_metadata": {
    "shopify_cust_id":"207119551"
  },
  "untrusted_metadata": {
    "onboarding_checklist": { "complete": true }
  },
  "emails": [
    {
      "email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
      "email": "test@example.com",
      "verified": true
    }
  ],
  "phone_numbers": [
    {
      "phone_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
      "phone_number": "+12025550162",
      "verified": true
    }
  ],
  "providers": [
    {
      "oauth_user_registration_id": "oauth-user-test-de86770c-911d-463f-80e7-f1b089cead14",
      "provider_subject": "10769150350006150715113082367",
      "provider_type": "Google",
      "profile_picture_url": "example.com",
      "locale": "en"
    }
  ],
  "webauthn_registrations": [
    {
      "webauthn_registration_id": "webauthn-registration-test-5c44cc6a-8af7-48d6-8da7-ea821342f5a6",
      "domain": "example.com",
      "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
      "authenticator_type": "platform",
      "verified": true
    }
  ],
  "biometric_registrations": [
    {
      "biometric_registration_id": "biometric-registration-test-6966a6fc-5264-46ee-9ba4-98c6322a5134",
      "verified": true
    }
  ],
  "totps": [
    {
      "totp_id": "totp-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c",
      "verified": true
    }
  ],
  "crypto_wallets": [
    {
      "crypto_wallet_id": "crypto-wallet-test-dbbd372e-79f8-48ea-907c-5f0755e7d328",
      "crypto_wallet_address": "0x6df2dB4Fb3DA35d241901Bd53367770BF03123f1",
      "crypto_wallet_type": "ethereum",
      "verified": true
    }
  ],
  "password": {
    "password_id": "password-test-ca6dbe77-10e5-4403-805a-b117c55c24c6",
    "requires_reset": false
  },
  "created_at": "2021-11-14T21:30:23Z",
  "status": "active"
}

Update user

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

Update a user's name or 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 Stytch 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

The user_id to update.

Body parameters

name object

The name of the user. If at least one name field is passed, all name fields will be updated.

Collapse

first_name string

The first name of the user. Replaces an existing first name, if it exists.

middle_name string

The middle name(s) of the user. Replaces an existing middle name, if it exists.

last_name string

The last name of the user. Replaces an existing last name, if it exists.

trusted_metadata object

The trusted_metadata field contains an arbitrary JSON object of application-specific data. See the Metadata reference for complete field behavior details.

untrusted_metadata object

attributes object

Provided attributes help with fraud detection.

Collapse

ip_address string

The IP address of the user.

user_agent string

The user agent of the user.

Response fields

status_code int

request_id string

user_id string

user object

The user object affected by this API call. See the Get user endpoint for complete response field details.

name object

The name object contains three values: first_name,middle_name,last_name.

emails object

The emails object contains an array of email objects for the user.

Collapse

email_id string

email string

The email address.

verified boolean

The verified boolean denotes whether or not this send method, e.g. phone number, email address etc, has been successfully authenticated by the user.

phone_numbers object

The phone_numbers array contains an array of phone number objects for the user.

Collapse

phone_id string

phone_number string

A phone number.

verified boolean

The verified boolean denotes whether or not this send method, e.g. phone number, email address etc, has been successfully authenticated by the user.

crypto_wallets array

The crypto_wallets array contains a list of all crypto wallets that a user has linked via Stytch.

Collapse

crypto_wallet_id string

crypto_wallet_address string

The crypto_wallet_address is the actual blockchain address of this user's crypto wallet.

crypto_wallet_type string

The crypto_wallet_type is the blockchain that the user's crypto wallet operates on, e.g. Ethereum, Solana, etc.

verified boolean

The verified boolean denotes whether or not this send method, e.g. phone number, email address etc, has been successfully authenticated by the user.

REQUEST

curl --request PUT \
	--url https://test.stytch.com/v1/users/user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6 \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "name": {
          "first_name": "Jane",
          "last_name": "Doe"
        },
	    "trusted_metadata": {
          "role": "ADMIN"
        }  
	  }'

RESPONSE

{
  "emails": [
    {
      "email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
      "email": "sandbox@stytch.com",
      "verified": false
    }
  ],
  "phone_numbers": [
    {
      "phone_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
      "phone_number": "+12025550162",
      "verified": false
    }
  ],
  "crypto_wallets": [
    {
      "crypto_wallet_id": "crypto-wallet-test-dbbd372e-79f8-48ea-907c-5f0755e7d328",
      "crypto_wallet_address": "0x6df2dB4Fb3DA35d241901Bd53367770BF03123f1",
      "crypto_wallet_type": "ethereum",
      "verified": true
    }
  ],
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "status_code": 200,
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "user": {...}
}

Delete user

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

Remove a user from Stytch.

Path parameters

user_id* string

The user_id to be deleted.

Response fields

status_code int

request_id string

user_id string

REQUEST

curl --request DELETE \
	--url https://test.stytch.com/v1/users/user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6 \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json'

RESPONSE

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

Delete user email

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

Remove an email from a given user.

Path parameters

email_id* string

The email_id to be deleted.

Response fields

status_code int

request_id string

user_id string

user object

The user object affected by this API call. See the Get user endpoint for complete response field details.

REQUEST

curl --request DELETE \
	--url https://test.stytch.com/v1/users/emails/email-test-81bf03a8-86e1-4d95-bd44-bb3495224953 \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json'

RESPONSE

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

Delete user phone number

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

Remove a phone number from a given user.

Path parameters

phone_id* string

The phone_id to be deleted.

Response fields

status_code int

request_id string

user_id string

user object

The user object affected by this API call. See the Get user endpoint for complete response field details.

REQUEST

curl --request DELETE \
	--url https://test.stytch.com/v1/users/phone_numbers/phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0 \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json'

RESPONSE

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

Delete user WebAuthn registration

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

Delete a previously created WebAuthn registration.

Path parameters

webauthn_registration_id* string

The webauthn_registration_id to be deleted.

Response fields

status_code int

request_id string

user_id string

user object

The user object affected by this API call. See the Get user endpoint for complete response field details.

REQUEST

curl --request DELETE \
	--url https://test.stytch.com/v1/users/webauthn_registrations/webauthn-registration-test-5c44cc6a-8af7-48d6-8da7-ea821342f5a6 \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json'

RESPONSE

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

Delete user biometric registration

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

Delete a previously created biometric registration.

Path parameters

biometric_registration_id* string

The biometric_registration_id to be deleted.

Response fields

status_code int

request_id string

user_id string

user object

The user object affected by this API call. See the Get user endpoint for complete response field details.

REQUEST

curl --request DELETE \
	--url https://test.stytch.com/v1/users/biometric_registrations/biometric-registration-test-6966a6fc-5264-46ee-9ba4-98c6322a5134 \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json'

RESPONSE

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

Delete user TOTP

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

Delete a previously created TOTP instance.

Path parameters

totp_id* string

The totp_id to be deleted.

Response fields

status_code int

request_id string

user_id string

user object

The user object affected by this API call. See the Get user endpoint for complete response field details.

REQUEST

curl --request DELETE \
	--url https://test.stytch.com/v1/users/totps/totp-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json'

RESPONSE

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

Delete user crypto wallet

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

Delete a crypto wallet.

Path parameters

crypto_wallet_id* string

The crypto_wallet_id to be deleted.

Response fields

status_code int

request_id string

user_id string

user object

The user object affected by this API call. See the Get user endpoint for complete response field details.

REQUEST

curl --request DELETE \
	--url https://test.stytch.com/v1/users/crypto_wallets/crypto-wallet-test-dbbd372e-79f8-48ea-907c-5f0755e7d328 \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json'

RESPONSE

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

Delete user password

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

Delete a password.

Path parameters

password_id* string

The password_id to be deleted.

Response fields

status_code int

request_id string

user_id string

user object

The user object affected by this API call. See the Get user endpoint for complete response field details.

REQUEST

curl --request DELETE \
	--url https://test.stytch.com/v1/users/passwords/password-test-ca6dbe77-10e5-4403-805a-b117c55c24c6 \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json'

RESPONSE

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

Delete user oauth registration

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

Delete an oauth user registration.

Path parameters

oauth_user_registration_id* string

The oauth_user_registration_id to be deleted.

Response fields

status_code int

request_id string

user_id string

user object

The user object affected by this API call. See the Get user endpoint for complete response field details.

REQUEST

curl --request DELETE \
      --url https://test.stytch.com/v1/users/oauth/oauth-user-test-de86770c-911d-463f-80e7-f1b089cead14 \
      -u 'PROJECT_ID:SECRET' \
      -H 'Content-Type: application/json'

RESPONSE

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

Get pending users

GEThttps://test.stytch.com/v1/users/pending

Fetch all users with a pending status. Users will show up here if they are added via the invite_by_email endpoint or via login_or_create where create_as_pending = true and have yet to create their account by clicking on the magic link in the email. All timestamps are formatted according to the RFC 3339 standard and are expressed in UTC, e.g. 2021-12-29T12:33:09Z.

Query parameters

limit int

The maximum number of users to be returned per API call.

starting_after_id string

The user ID to start after.

Response fields

status_code int

request_id string

users array[object]

An array of User objects.

has_more boolean

Response has been paginated and another request should be made by passing next_starting_after_id

next_starting_after_id string

Bookmark value for paginated responses

total int

Total number of pending users

REQUEST

curl --request GET \
	--url https://test.stytch.com/v1/users/pending \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	--get \
	--data-urlencode 'limit=100'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "users": [
    {
      "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
      "name": {
        "first_name": "Jane",
        "middle_name": "",
        "last_name": "Doe"
      },
      "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
        }
      ],
      "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": {},
      "status": "pending",
      "created_at": "2020-12-18T07:41:52Z",
      "invited_at": "2020-12-18T07:41:52Z"
    }
  ],
  "has_more": false,
  "next_starting_after_id": "",
  "total": 1
}

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

The email of the user to send the invite magic link to.

login_magic_link_url string

The URL that users click from the login email magic link. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's authenticate endpoint and finishes the login. If this value is not passed, the default login redirect URL that you set in your Dashboard is used. If you have not set a default login redirect URL, an error is returned.

signup_magic_link_url string

The url the user clicks from the sign-up email magic link. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's authenticate endpoint and finishes the login. If this value is not passed, the default sign-up redirect URL that you set in your Dashboard is used. If you have not set a default sign-up redirect URL, an error is returned.

login_expiration_minutes int

Set the expiration for the login email magic link, in minutes. By default, it expires in 1 hour. The minimum expiration is 5 minutes and the maximum is 7 days (10080 mins).

signup_expiration_minutes int

Set the expiration for the sign-up email magic link, in minutes. By default, it expires in 1 week. The minimum expiration is 5 minutes and the maximum is 7 days (10080 mins).

login_template_id string

Use a custom template for login emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for Magic links - Login.

signup_template_id string

Use a custom template for sign-up emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for Magic links - Sign-up.

locale string

Used to determine which language to use when sending the user this delivery method. Parameter is a IETF BCP 47 language tag, e.g. "en".

Currently supported languages are English ("en"), Spanish ("es"), and Brazilian Portuguese ("pt-br"); if no value is provided, the copy defaults to English.

Request support for additional languages here!

attributes object

Provided attributes help with fraud detection. When authenticating a user's magic link token, you can require the IP address and/or the user agent to match that user's attributes when they originated the initial authentication request. To enable this functionality, you can use the options parameter in AuthenticateMagic.

Collapse

ip_address string

The IP address of the user.

user_agent string

The user agent of the user.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device.

user_id string

The user_id of the user to associate the email with. This parameter allows you to associate a new email address with an existing Stytch User.

Only include a user_id if the user in question already has an active and valid session at the time of the send operation; without this safety check a malicious user may use this as an account takeover vector.

session_token string

The session_token belonging to the user that you wish to associate the email with.

session_jwt string

The session_jwt belonging to the user that you wish to associate the email with.

Response fields

status_code int

request_id string

user_id string

email_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/magic_links/email/send \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "email": "sandbox@stytch.com"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
}

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

The email of the user to send the invite magic link to.

login_magic_link_url string

The url the user clicks from the login email magic link. This should be a url that your app receives and parses and subsequently send an API request to authenticate the magic link and log in the user. If this value is not passed, the default login redirect URL that you set in your Dashboard is used. If you have not set a default login redirect URL, an error is returned.

signup_magic_link_url string

The url the user clicks from the sign-up email magic link. This should be a url that your app receives and parses and subsequently send an api request to authenticate the magic link and sign-up the user. If this value is not passed, the default sign-up redirect URL that you set in your Dashboard is used. If you have not set a default sign-up redirect URL, an error is returned.

login_expiration_minutes int

Set the expiration for the login email magic link, in minutes. By default, it expires in 1 hour. The minimum expiration is 5 minutes and the maximum is 7 days (10080 mins).

signup_expiration_minutes int

Set the expiration for the sign-up email magic link, in minutes. By default, it expires in 1 week. The minimum expiration is 5 minutes and the maximum is 7 days (10080 mins).

login_template_id string

Use a custom template for login emails. By default, it will use your default email template The template must be a template using our built-in customizations or a custom HTML email for Magic links - Login.

signup_template_id string

create_user_as_pending boolean

Flag for whether or not to save a user as pending vs active in Stytch. Defaults to false. If true, new users will be created with status pending in Stytch's backend. Their status will remain pending and they will continue to receive sign-up magic links until a magic link is authenticated for that user. If false, new users will be created with status active. They will receive a sign-up magic link for their first magic link but subsequent magic links will use the login email template, even if the user never authenticated their initial magic link.

locale string

attributes object

Collapse

ip_address string

The IP address of the user.

user_agent string

The user agent of the user.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device.

Response fields

status_code int

request_id string

user_id string

email_id string

user_created boolean

In login_or_create endpoints, this field indicates whether or not a user was freshly created or the user went through a login path.

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/magic_links/email/login_or_create \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "email": "sandbox@stytch.com"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
  "user_created": true
}

Invite by email

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

Create a pending 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

The email of the user to send the invite magic link to.

invite_magic_link_url string

The url the user clicks from the email magic link. This should be a url that your app receives and parses and subsequently send an api request to authenticate the magic link and log in the user. If this value is not passed, the default invite redirect URL that you set in your Dashboard is used. If you have not set a default invite redirect URL, an error is returned.

invite_expiration_minutes int

Set the expiration for the email magic link, in minutes. By default, it expires in 1 hour. The minimum expiration is 5 minutes and the maximum is 7 days (10080 mins).

invite_template_id string

Use a custom template for invite emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for Magic links - Invite.

name object

The name of the user. Each field in the name object is optional.

Collapse

first_name string

The first name of the user.

middle_name string

The middle name(s) of the user.

last_name string

The last name of the user.

locale string

attributes object

Provided attributes help with fraud detection.

Collapse

ip_address string

The IP address of the user.

user_agent string

The user agent of the user.

Response fields

status_code int

request_id string

user_id string

email_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/magic_links/email/invite \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "email": "sandbox@stytch.com"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
}

Revoke a pending invite

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

Revoke a pending invite based on the email provided.

Body parameters

email* string

The email of the user to revoke invite for.

Response fields

status_code int

request_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/magic_links/email/revoke_invite \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "email": "sandbox@stytch.com"
	}'

RESPONSE

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

Embeddable magic links overview

With our out-of-the-box email magic links product, Stytch is able to fully handle the frustrating and complex pieces of email deliverability, latency, and inbox placement. However, we also offer a flexible way for you to embed magic links into any use case you can imagine. For example, you could send magic links from your own domain, embed them into customized templates, or leverage different communication channels, like sms, to send them. By using our magic link create endpoint, you can embed magic links into all of your end-user communications to reduce friction and improve conversion. If needed, you can always add more authentication requirements to a user’s session to improve security by using the rest of Stytch’s product suite.

Create embeddable magic link

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

Create a magic link token for a user. Access to this endpoint is restricted, to be enabled for it, please send us a note at support@stytch.com.

Next steps

Send the returned token value to the user in a link which directs to your application. When the user follows your link, collect the token, and call Authenticate magic link to complete authentication.

Body parameters

user_id* string

The user ID for the magic link token.

expiration_minutes int

Set the expiration for the magic token, in minutes. By default, it expires in 1 hour. The minimum expiration is 5 minutes and the maximum is 7 days (10080 mins).

attributes object

Collapse

ip_address string

The IP address of the user.

user_agent string

The user agent of the user.

Response fields

status_code int

request_id string

user_id string

token string

The magic link token that you'll include in your contact method of choice, e.g. email or SMS. Check out our Embeddable magic link guide for more detail on where to include the token.

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/magic_links \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
	}'

RESPONSE

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

Authenticate magic link

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

Authenticate a user given a magic link. This endpoint verifies that the magic link token is valid, hasn't expired or been previously used, and any optional security settings such as IP match or user agent match are satisfied.

Body parameters

token* string

The token to authenticate.

options object

Specify optional security settings

Collapse

ip_match_required boolean

Require that the IP address the magic link was requested from matches the IP address it's clicked from.

user_agent_match_required boolean

Require that the user agent the magic link was requested from matches the user agent it's clicked from.

attributes object

Provided attributes help with fraud detection. You can require the IP address and/or the user agent to match the request used to send the magic link using the options parameter.

Collapse

ip_address string

The IP address of the user.

user_agent string

The user agent of the user.

session_duration_minutes int

Set the session lifetime to be this many minutes from now. This will start a new session if one doesn't already exist, returning both an opaque session_token and session_jwt for this session. Remember that the session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will need to be refreshed over time.

This value must be a minimum of 5 and a maximum of 527040 minutes (366 days).

If a session_token or session_jwt is provided then a successful authentication will continue to extend the session this many minutes.

If the session_duration_minutes parameter is not specified, a Stytch session will not be created.

session_custom_claims map<string, any>

Add a custom claims map to the session being authenticated. Claims are only created if a session is initialized by providing a value in session duration minutes. Claims will be included on the session object and in the JWT. To update a key in an existing session, supply a new value. To delete a key, supply a null value
Custom claims made with reserved claims ("iss", "sub", "aud", "exp", "nbf", "iat", "jti") will be ignored. Total custom claims size cannot exceed four kilobytes

session_jwt string

Reuse an existing session instead of creating a new one. If you provide us with a session_jwt, then we'll update the session represented by this JWT with this magic link factor. If this session_jwt belongs to a different user than the magic token, the session_jwt will be ignored. This endpoint will error if both session_token and session_jwt are provided.

session_token string

Reuse an existing session instead of creating a new one. If you provide us with a session_token, then we'll update the session represented by this session token with this magic link factor. If this session_token belongs to a different user than the magic token, the session_token will be ignored. This endpoint will error if both session_token and session_jwt are provided.

code_verifier string

A base64url encoded one time secret used to validate that the request starts and ends on the same device.

Response fields

method_id string

The email_id or phone_id involved in the given authentication.

request_id string

reset_sessions boolean

Indicates if all other of this user's sessions need to be reset. You should check this field if you aren't using Stytch's Session product. If you are using Stytch's Session product, we revoke the user's other sessions for you.

session object

If you initiate a session, by including session_duration_minutes in your authenticate call, you'll receive a full session object in the response.

See GET sessions for complete response fields.

session_jwt string

The JSON Web Token (JWT) for a given Stytch session. Read more about JWTs in our session management guide.

session_token string

A secret token for a given Stytch session. Read more about session_token in our session management guide.

status_code int

user object

The user object affected by this API call. See the Get user endpoint for complete response field details.

user_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/magic_links/authenticate \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	  "token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4="
	}'

RESPONSE

{
  "method_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "reset_sessions": false,
  "session": null,
  "session_jwt": "",
  "session_token": "",
  "status_code": 200,
  "user": {...},
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6" 
}

SMS 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.

Your users are global and so are we, we support every country available to us for SMS passcodes, countries that we do not support 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

The phone number of the user to send a one-time passcode.The phone number should be in E.164 format (i.e. +1XXXXXXXXXX). You may use +10000000000 to test this endpoint, see Testing for more detail.

expiration_minutes int

Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.

locale string

attributes object

Provided attributes help with fraud detection. When authenticating a user's provided passcode, you can require the IP address and/or the user agent to match that user's attributes when they originated the initial authentication request. To enable this functionality, you can use the options parameter in AuthenticateOTP.

Collapse

ip_address string

The IP address of the user.

user_agent string

The user agent of the user.

user_id string

The user_id of the user to associate the phone number with. This parameter allows you to associate a new email address with an existing Stytch User.

Only include a user_id if the user in question already has an active and valid session at the time of the send operation; without this safety check a malicious user may use this as an account takeover vector.

session_token string

The session_token belonging to the user that you wish to associate the phone number with.

session_jwt string

The session_jwt belonging to the user that you wish to associate the phone number with.

Response fields

status_code int

request_id string

user_id string

phone_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/otps/sms/send \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "phone_number": "+12025550162"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "phone_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0"
}

Log in or create user by SMS

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

The phone number of the user to send a one-time passcode.The phone number should be in E.164 format (i.e. +1XXXXXXXXXX). You may use +10000000000 to test this endpoint, see Testing for more detail.

expiration_minutes int

Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.

locale string

create_user_as_pending boolean

Flag for whether or not to save a user as pending vs active in Stytch. Defaults to false. If true, users will be saved with status pending in Stytch's backend until the invite is accepted by entering an OTP code. If false, users will be created as active. An example usage of a true flag would be to require users to verify their phone by entering the OTP code before creating an account for them.

attributes object

Collapse

ip_address string

The IP address of the user.

user_agent string

The user agent of the user.

Response fields

status_code int

request_id string

user_id string

phone_id string

user_created boolean

In login_or_create endpoints, this field indicates whether or not a user was freshly created or the user went through a login path.

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/otps/sms/login_or_create \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "phone_number": "+12025550162"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "phone_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
  "user_created": true
}

Send one-time passcode by WhatsApp

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

Send a one-time passcode (OTP) to a user's WhatsApp using their 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

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

The phone number of the user to send a one-time passcode.The phone number should be in E.164 format (i.e. +1XXXXXXXXXX). You may use +10000000000 to test this endpoint, see Testing for more detail.

expiration_minutes int

Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.

locale string

attributes object

Collapse

ip_address string

The IP address of the user.

user_agent string

The user agent of the user.

user_id string

session_token string

The session_token belonging to the user that you wish to associate the phone number with.

session_jwt string

The session_jwt belonging to the user that you wish to associate the phone number with.

Response fields

status_code int

request_id string

user_id string

phone_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/otps/whatsapp/send \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "phone_number": "+12025550162"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "phone_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0"
}

Log in or create user by WhatsApp

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

The phone number of the user to send a one-time passcode.The phone number should be in E.164 format (i.e. +1XXXXXXXXXX). You may use +10000000000 to test this endpoint, see Testing for more detail.

expiration_minutes int

Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.

locale string

create_user_as_pending boolean

attributes object

Collapse

ip_address string

The IP address of the user.

user_agent string

The user agent of the user.

Response fields

status_code int

request_id string

user_id string

phone_id string

user_created boolean

In login_or_create endpoints, this field indicates whether or not a user was freshly created or the user went through a login path.

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/otps/whatsapp/login_or_create \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "phone_number": "+12025550162"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "phone_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
  "user_created": true
}

Email one-time passcodes overview

Email passcodes sends a one-time passcode (OTP) to the user's email. The user will then submit that code to your app.

Send one-time passcode by email

POSThttps://test.stytch.com/v1/otps/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.

Note that sending another OTP code before the first has expired will invalidate the first code.

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 address to an existing Stytch User requires the user to be present and validate the email address 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 email_id found in the response as the method_id.

Body parameters

email* string

The email address of the user to send the one-time passcode to. You may use sandbox@stytch.com to test this endpoint, see Testing for more detail.

expiration_minutes int

Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.

login_template_id string

Use a custom template for login emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for OTP - Login.

signup_template_id string

locale string

attributes object

Collapse

ip_address string

The IP address of the user.

user_agent string

The user agent of the user.

user_id string

session_token string

The session_token belonging to the user that you wish to associate the email with.

session_jwt string

The session_jwt belonging to the user that you wish to associate the email with.

Response fields

status_code int

request_id string

user_id string

email_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/otps/email/send \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "email": "sandbox@stytch.com"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
}

Log in or create user by email OTP

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 email_id found in the response as the method_id.

Body parameters

email* string

The email address of the user to send the one-time passcode to. You may use sandbox@stytch.com to test this endpoint, see Testing for more detail.

expiration_minutes int

Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.

login_template_id string

Use a custom template for login emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for OTP - Login.

signup_template_id string

locale string

create_user_as_pending boolean

Flag for whether or not to save a user as pending vs active in Stytch. Defaults to false. If true, users will be saved with status pending in Stytch's backend until the invite is accepted by entering an OTP code. If false, users will be created as active. An example usage of a true flag would be to require users to verify their email by entering the OTP code before creating an account for them.

attributes object

Collapse

ip_address string

The IP address of the user.

user_agent string

The user agent of the user.

Response fields

status_code int

request_id string

user_id string

email_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/otps/email/login_or_create \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "email": "sandbox@stytch.com"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
  "user_created": true
}

Authenticate 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

The email_id or phone_id where the OTP was delivered. This value will be returned in the associated /login_or_create or /send response.

code* string

The code to authenticate.

options object

Specify optional security settings

Collapse

ip_match_required boolean

Require that the IP address the one-time passcode was requested from matches the IP address upon code entry.

user_agent_match_required boolean

Require that the user agent the one-time passcode was requested from matches the user agent upon code entry.

attributes object

Provided attributes help with fraud detection. You can require the IP address and/or the user agent to match the request used to send the OTP code link using the options parameter.

Collapse

ip_address string

The IP address of the user.

user_agent string

The user agent of the user.

session_custom_claims map<string, any>

session_duration_minutes int

session_jwt string

Reuse an existing session instead of creating a new one. If you provide us with a session_jwt, then we'll update the session represented by this JWT with this OTP factor. If this session_jwt belongs to a different user than the OTP code, the session_jwt will be ignored. This endpoint will error if both session_token and session_jwt are provided.

session_token string

Reuse an existing session instead of creating a new one. If you provide us with a session_token, then we'll update the session represented by this session token with this OTP factor. If this session_token belongs to a different user than the OTP code, the session_token will be ignored. This endpoint will error if both session_token and session_jwt are provided.

Response fields

reset_sessions boolean

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/otps/authenticate \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "method_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
        "code": "123456"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "user": {...},
  "method_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
  "reset_sessions": false,
  "session_jwt": "",
  "session_token": "",
  "session": null
}

OAuth 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_jwtmust 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

The OAuth provider's name.

user_id string

The user ID of the target user.

session_token string

An active session token for the target user.

session_jwt string

An active session JWT for the target user.

Response fields

status_code int

request_id string

oauth_attach_token string

A single-use token for connecting the Stytch User selection from an OAuth Attach request to the corresponding OAuth Start request.

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/oauth/attach \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
    "provider": "google",
    "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
	}'

RESPONSE

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

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_urlor 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

The public token from the Stytch dashboard is safe to embed client side. The public token authenticates the request instead of the project ID and secret since this endpoint is called client side instead of from the backend server.

login_redirect_url string

The URL Stytch redirects to after the OAuth flow is completed for a user that already exists. This URL should be a route in your application which will run oauth.authenticate (see below) and finish the login.

The URL must be configured as a Login URL in the Redirect URL page. If the field is not specified, the default Login URL will be used.

signup_redirect_url string

The URL Stytch redirects to after the OAuth flow is completed for a user that does not yet exist. This URL should be a route in your application which will run oauth.authenticate (see below) and finish the login.

The URL must be configured as a Sign Up URL in the Redirect URL page. If the field is not specified, the default Sign Up URL will be used.

custom_scopes string

Include a space separated list of custom scopes that you'd like to include. Note that this list must be URL encoded, i.e. the spaces must be expressed as %20.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device. See the PKCE OAuth guide for usage instructions.

oauth_attach_token string

A single-use token for connecting the Stytch User selection from an OAuth Attach request to the corresponding OAuth Start request.

Response fields

status_code int

request_id string

redirect_url string

The url to redirect to. This should be done automatically by the browser.

REQUEST

curl \
    --url "https://test.stytch.com/v1/public/oauth/google/start?public_token=PUBLIC_TOKEN&login_redirect_url=https%3A%2F%2Fexample.com%2Flogin&\
signup_redirect_url=https%3A%2F%2Fexample.com%2Fsignup"

RESPONSE

{
    "status_code": 302,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "redirect_url": "https://accounts.google.com/o/oauth2/v2/auth/identifier?client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=openid%20email%20profile&access_type=offline&state=example-state",
  }

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_urlor signup_redirect_url provided.

Scopes

By default our Amazon OAuth integration includes profile scope. You may add the additional Amazon API scopes profile:user_id and postal_code, 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_url string

The URL must be configured as a Login URL in the Redirect URL page. If the field is not specified, the default Login URL will be used.

signup_redirect_url string

The URL must be configured as a Sign Up URL in the Redirect URL page. If the field is not specified, the default Sign Up URL will be used.

custom_scopes string

Include a space separated list of custom scopes that you'd like to include. Note that this list must be URL encoded, i.e. the spaces must be expressed as %20.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device. See the PKCE OAuth guide for usage instructions.

oauth_attach_token string

A single-use token for connecting the Stytch User selection from an OAuth Attach request to the corresponding OAuth Start request.

Response fields

status_code int

request_id string

redirect_url string

The url to redirect to. This should be done automatically by the browser.

REQUEST

curl \
    --url "https://test.stytch.com/v1/public/oauth/amazon/start?public_token=PUBLIC_TOKEN&login_redirect_url=https%3A%2F%2Fexample.com%2Flogin&\
signup_redirect_url=https%3A%2F%2Fexample.com%2Fsignup"

RESPONSE

{
    "status_code": 302,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "redirect_url": "https://amazon.com/api/oauth2/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=identify%3Aemail&state=example-state",
  }

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_urlor signup_redirect_url provided.

Scopes

By default our Apple OAuth integration includes name and email scopes. Apple does not support any scopes beyond these two, no custom scopes are available.

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_url string

The URL must be configured as a Login URL in the Redirect URL page. If the field is not specified, the default Login URL will be used.

signup_redirect_url string

The URL must be configured as a Sign Up URL in the Redirect URL page. If the field is not specified, the default Sign Up URL will be used.

custom_scopes string

Include a space separated list of custom scopes that you'd like to include. Note that this list must be URL encoded, i.e. the spaces must be expressed as %20.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device. See the PKCE OAuth guide for usage instructions.

oauth_attach_token string

A single-use token for connecting the Stytch User selection from an OAuth Attach request to the corresponding OAuth Start request.

Response fields

status_code int

request_id string

redirect_url string

The url to redirect to. This should be done automatically by the browser.

REQUEST

curl \
    --url "https://test.stytch.com/v1/public/oauth/apple/start?public_token=PUBLIC_TOKEN&login_redirect_url=https%3A%2F%2Fexample.com%2Flogin&\
signup_redirect_url=https%3A%2F%2Fexample.com%2Fsignup"

RESPONSE

{
    "status_code": 302,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "redirect_url": "https://appleid.apple.com/auth/authorize?client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&response_mode=form_post&scope=name%20email&state=example-state",
  }

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_urlor signup_redirect_url provided.

Scopes

By default our Bitbucket OAuth integration includes account and email 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_url string

The URL must be configured as a Login URL in the Redirect URL page. If the field is not specified, the default Login URL will be used.

signup_redirect_url string

The URL must be configured as a Sign Up URL in the Redirect URL page. If the field is not specified, the default Sign Up URL will be used.

custom_scopes string

Include a space separated list of custom scopes that you'd like to include. Note that this list must be URL encoded, i.e. the spaces must be expressed as %20.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device. See the PKCE OAuth guide for usage instructions.

oauth_attach_token string

A single-use token for connecting the Stytch User selection from an OAuth Attach request to the corresponding OAuth Start request.

Response fields

status_code int

request_id string

redirect_url string

The url to redirect to. This should be done automatically by the browser.

REQUEST

curl \
    --url "https://test.stytch.com/v1/public/oauth/bitbucket/start?public_token=PUBLIC_TOKEN&login_redirect_url=https%3A%2F%2Fexample.com%2Flogin&\
signup_redirect_url=https%3A%2F%2Fexample.com%2Fsignup"

RESPONSE

{
    "status_code": 302,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "redirect_url": "https://bitbucket.com/api/oauth2/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=identify%3Aemail&state=example-state",
  }

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_urlor signup_redirect_url provided.

Scopes

By default our Coinbase OAuth integration includes account and email 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_url string

The URL must be configured as a Login URL in the Redirect URL page. If the field is not specified, the default Login URL will be used.

signup_redirect_url string

The URL must be configured as a Sign Up URL in the Redirect URL page. If the field is not specified, the default Sign Up URL will be used.

custom_scopes string

Include a space separated list of custom scopes that you'd like to include. Note that this list must be URL encoded, i.e. the spaces must be expressed as %20.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device. See the PKCE OAuth guide for usage instructions.

oauth_attach_token string

A single-use token for connecting the Stytch User selection from an OAuth Attach request to the corresponding OAuth Start request.

Response fields

status_code int

request_id string

redirect_url string

The url to redirect to. This should be done automatically by the browser.

REQUEST

curl \
    --url "https://test.stytch.com/v1/public/oauth/coinbase/start?public_token=PUBLIC_TOKEN&login_redirect_url=https%3A%2F%2Fexample.com%2Flogin&\
signup_redirect_url=https%3A%2F%2Fexample.com%2Fsignup"

RESPONSE

{
    "status_code": 302,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "redirect_url": "https://coinbase.com/api/oauth2/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=identify%3Aemail&state=example-state",
  }

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_urlor signup_redirect_url provided.

Scopes

By default our Discord OAuth integration includes identify and email 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_url string

The URL must be configured as a Login URL in the Redirect URL page. If the field is not specified, the default Login URL will be used.

signup_redirect_url string

The URL must be configured as a Sign Up URL in the Redirect URL page. If the field is not specified, the default Sign Up URL will be used.

custom_scopes string

Include a space separated list of custom scopes that you'd like to include. Note that this list must be URL encoded, i.e. the spaces must be expressed as %20.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device. See the PKCE OAuth guide for usage instructions.

oauth_attach_token string

A single-use token for connecting the Stytch User selection from an OAuth Attach request to the corresponding OAuth Start request.

Response fields

status_code int

request_id string

redirect_url string

The url to redirect to. This should be done automatically by the browser.

REQUEST

curl \
    --url "https://test.stytch.com/v1/public/oauth/discord/start?public_token=PUBLIC_TOKEN&login_redirect_url=https%3A%2F%2Fexample.com%2Flogin&\
signup_redirect_url=https%3A%2F%2Fexample.com%2Fsignup"

RESPONSE

{
    "status_code": 302,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "redirect_url": "https://discord.com/api/oauth2/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=identify%3Aemail&state=example-state",
  }

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_urlor signup_redirect_url provided. This endpoint allows logging in just with Facebook, not with other Meta products such as Instagram or WhatsApp.

Scopes

By default our Facebook OAuth integration includes email and public_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_url string

The URL must be configured as a Login URL in the Redirect URL page. If the field is not specified, the default Login URL will be used.

signup_redirect_url string

The URL must be configured as a Sign Up URL in the Redirect URL page. If the field is not specified, the default Sign Up URL will be used.

custom_scopes string

Include a space separated list of custom scopes that you'd like to include. Note that this list must be URL encoded, i.e. the spaces must be expressed as %20.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device. See the PKCE OAuth guide for usage instructions.

oauth_attach_token string

A single-use token for connecting the Stytch User selection from an OAuth Attach request to the corresponding OAuth Start request.

Response fields

status_code int

request_id string

redirect_url string

The url to redirect to. This should be done automatically by the browser.

REQUEST

curl \
      --url "https://test.stytch.com/v1/public/oauth/facebook/start?public_token=PUBLIC_TOKEN&login_redirect_url=https%3A%2F%2Fexample.com%2Flogin&\
  signup_redirect_url=https%3A%2F%2Fexample.com%2Fsignup"

RESPONSE

{
      "status_code": 302,
      "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
      "redirect_url": "https://www.facebook.com/v12.0/dialog/oauth?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=email+public_profile&state=example-state",
    }

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_urlor signup_redirect_url provided.

Scopes

Figma's API only contains a single scope, file_read, this scope is included by default. You can read more about Figma's scopes in their documentation.

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_url string

The URL must be configured as a Login URL in the Redirect URL page. If the field is not specified, the default Login URL will be used.

signup_redirect_url string

The URL must be configured as a Sign Up URL in the Redirect URL page. If the field is not specified, the default Sign Up URL will be used.

custom_scopes string

Include a space separated list of custom scopes that you'd like to include. Note that this list must be URL encoded, i.e. the spaces must be expressed as %20.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device. See the PKCE OAuth guide for usage instructions.

oauth_attach_token string

A single-use token for connecting the Stytch User selection from an OAuth Attach request to the corresponding OAuth Start request.

Response fields

status_code int

request_id string

redirect_url string

The url to redirect to. This should be done automatically by the browser.

REQUEST

curl \
    --url "https://test.stytch.com/v1/public/oauth/figma/start?public_token=PUBLIC_TOKEN&login_redirect_url=https%3A%2F%2Fexample.com%2Flogin&\
signup_redirect_url=https%3A%2F%2Fexample.com%2Fsignup"

RESPONSE

{
    "status_code": 302,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "redirect_url": "https://www.figma.com/oauth?access_type=offline&client_id=M1M5R3BMVy13QmpScXkzTUt5OE46MTpjaQ&redirect_uri=https%3A%2F%2Ftest.stytch.com%2Fv1%2Foauth%2Fcallback%2Foauth-callback-test-7ead456f-7871-47a3-9ee5-f0002b03d05f&response_type=code&scope=file_read&state=Figma%3ASQ8MiSdQy1UmZ1sdMkcC1T28bOr2qvO-3-LtuidPd8kX",
  }

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_urlor signup_redirect_url provided.

Scopes

By default our GitHub OAuth integration includes the user:email scope. 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_url string

The URL must be configured as a Login URL in the Redirect URL page. If the field is not specified, the default Login URL will be used.

signup_redirect_url string

The URL must be configured as a Sign Up URL in the Redirect URL page. If the field is not specified, the default Sign Up URL will be used.

custom_scopes string

Include a space separated list of custom scopes that you'd like to include. Note that this list must be URL encoded, i.e. the spaces must be expressed as %20.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device. See the PKCE OAuth guide for usage instructions.

oauth_attach_token string

A single-use token for connecting the Stytch User selection from an OAuth Attach request to the corresponding OAuth Start request.

Response fields

status_code int

request_id string

redirect_url string

The url to redirect to. This should be done automatically by the browser.

REQUEST

curl \
    --url "https://test.stytch.com/v1/public/oauth/github/start?public_token=PUBLIC_TOKEN&login_redirect_url=https%3A%2F%2Fexample.com%2Flogin&\
signup_redirect_url=https%3A%2F%2Fexample.com%2Fsignup"

RESPONSE

{
    "status_code": 302,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "redirect_url": "https://github.com/login/oauth/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=user%3Aemail&state=example-state",
  }

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_urlor signup_redirect_url 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_url string

The URL must be configured as a Login URL in the Redirect URL page. If the field is not specified, the default Login URL will be used.

signup_redirect_url string

The URL must be configured as a Sign Up URL in the Redirect URL page. If the field is not specified, the default Sign Up URL will be used.

custom_scopes string

Include a space separated list of custom scopes that you'd like to include. Note that this list must be URL encoded, i.e. the spaces must be expressed as %20.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device. See the PKCE OAuth guide for usage instructions.

oauth_attach_token string

A single-use token for connecting the Stytch User selection from an OAuth Attach request to the corresponding OAuth Start request.

Response fields

status_code int

request_id string

redirect_url string

The url to redirect to. This should be done automatically by the browser.

REQUEST

curl \
    --url "https://test.stytch.com/v1/public/oauth/gitlab/start?public_token=PUBLIC_TOKEN&login_redirect_url=https%3A%2F%2Fexample.com%2Flogin&\
signup_redirect_url=https%3A%2F%2Fexample.com%2Fsignup"

RESPONSE

{
    "status_code": 302,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "redirect_url": "https://gitlab.com/login/oauth/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=user%3Aemail&state=example-state",
  }

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_urlor signup_redirect_url provided.

Scopes

By default our LinkedIn OAuth integration includes r_liteprofile and r_emailaddress scopes. You may add any additional LinkedIn API scopes by adding additional products to your application, 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_url string

The URL must be configured as a Login URL in the Redirect URL page. If the field is not specified, the default Login URL will be used.

signup_redirect_url string

The URL must be configured as a Sign Up URL in the Redirect URL page. If the field is not specified, the default Sign Up URL will be used.

custom_scopes string

Include a space separated list of custom scopes that you'd like to include. Note that this list must be URL encoded, i.e. the spaces must be expressed as %20.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device. See the PKCE OAuth guide for usage instructions.

oauth_attach_token string

A single-use token for connecting the Stytch User selection from an OAuth Attach request to the corresponding OAuth Start request.

Response fields

status_code int

request_id string

redirect_url string

The url to redirect to. This should be done automatically by the browser.

REQUEST

curl \
    --url "https://test.stytch.com/v1/public/oauth/linkedin/start?public_token=PUBLIC_TOKEN&login_redirect_url=https%3A%2F%2Fexample.com%2Flogin&\
signup_redirect_url=https%3A%2F%2Fexample.com%2Fsignup"

RESPONSE

{
    "status_code": 302,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "redirect_url": "https://linkedin.com/api/oauth2/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=identify%3Aemail&state=example-state",
  }

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_urlor signup_redirect_url 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_url string

The URL must be configured as a Login URL in the Redirect URL page. If the field is not specified, the default Login URL will be used.

signup_redirect_url string

The URL must be configured as a Sign Up URL in the Redirect URL page. If the field is not specified, the default Sign Up URL will be used.

custom_scopes string

Include a space separated list of custom scopes that you'd like to include. Note that this list must be URL encoded, i.e. the spaces must be expressed as %20.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device. See the PKCE OAuth guide for usage instructions.

oauth_attach_token string

A single-use token for connecting the Stytch User selection from an OAuth Attach request to the corresponding OAuth Start request.

Response fields

status_code int

request_id string

redirect_url string

The url to redirect to. This should be done automatically by the browser.

REQUEST

curl \
    --url "https://test.stytch.com/v1/public/oauth/microsoft/start?public_token=PUBLIC_TOKEN&login_redirect_url=https%3A%2F%2Fexample.com%2Flogin&\
signup_redirect_url=https%3A%2F%2Fexample.com%2Fsignup"

RESPONSE

{
    "status_code": 302,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "redirect_url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=openid+email+profile&state=example-state",
  }

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_urlor signup_redirect_url provided.

Scopes

By default our Slack OAuth integration includes openid, email, and profile scopes. You may add additional User 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_url string

The URL must be configured as a Login URL in the Redirect URL page. If the field is not specified, the default Login URL will be used.

signup_redirect_url string

The URL must be configured as a Sign Up URL in the Redirect URL page. If the field is not specified, the default Sign Up URL will be used.

custom_scopes string

Include a space separated list of custom scopes that you'd like to include. Note that this list must be URL encoded, i.e. the spaces must be expressed as %20.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device. See the PKCE OAuth guide for usage instructions.

oauth_attach_token string

A single-use token for connecting the Stytch User selection from an OAuth Attach request to the corresponding OAuth Start request.

Response fields

status_code int

request_id string

redirect_url string

The url to redirect to. This should be done automatically by the browser.

REQUEST

curl \
    --url "https://test.stytch.com/v1/public/oauth/slack/start?public_token=PUBLIC_TOKEN&login_redirect_url=https%3A%2F%2Fexample.com%2Flogin&\
signup_redirect_url=https%3A%2F%2Fexample.com%2Fsignup"

RESPONSE

{
    "status_code": 302,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "redirect_url": "https://slack.com/oauth/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=openid%3Aprofile%3Aemail&state=example-state",
  }

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_urlor signup_redirect_url provided.

Scopes

Snapchat uses user.display_name, user.bitmoji.avatar, and user.external_id scopes by default. For more information on scopes, see Snapchat's documentation.

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_url string

The URL must be configured as a Login URL in the Redirect URL page. If the field is not specified, the default Login URL will be used.

signup_redirect_url string

The URL must be configured as a Sign Up URL in the Redirect URL page. If the field is not specified, the default Sign Up URL will be used.

custom_scopes string

Include a space separated list of custom scopes that you'd like to include. Note that this list must be URL encoded, i.e. the spaces must be expressed as %20.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device. See the PKCE OAuth guide for usage instructions.

oauth_attach_token string

A single-use token for connecting the Stytch User selection from an OAuth Attach request to the corresponding OAuth Start request.

Response fields

status_code int

request_id string

redirect_url string

The url to redirect to. This should be done automatically by the browser.

REQUEST

curl \
    --url "https://test.stytch.com/v1/public/oauth/snapchat/start?public_token=PUBLIC_TOKEN&login_redirect_url=https%3A%2F%2Fexample.com%2Flogin&\
signup_redirect_url=https%3A%2F%2Fexample.com%2Fsignup"

RESPONSE

{
    "status_code": 302,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "redirect_url": "https://accounts.snapchat.com/accounts/oauth2/auth?access_type=offline&client_id=M1M5R3BMVy13QmpScXkzTUt5OE46MTpjaQ&redirect_uri=https%3A%2F%2Ftest.stytch.com%2Fv1%2Foauth%2Fcallback%2Foauth-callback-test-7ead456f-7871-47a3-9ee5-f0002b03d05f&response_type=code&scope=https%3A%2F%2Fauth.snapchat.com%2Foauth2%2Fapi%2Fuser.display_name+https%3A%2F%2Fauth.snapchat.com%2Foauth2%2Fapi%2Fuser.bitmoji.avatar+https%3A%2F%2Fauth.snapchat.com%2Foauth2%2Fapi%2Fuser.external_id&state=Snapchat%3AW_jLEECBVSRY0yc8i3UG_h-4k95V1K90LlXuWBATL2KM",
  }

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_urlor signup_redirect_url provided.

Scopes

By default our TikTok OAuth integration includes the user.info.basic scope. You may add 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_url string

The URL must be configured as a Login URL in the Redirect URL page. If the field is not specified, the default Login URL will be used.

signup_redirect_url string

The URL must be configured as a Sign Up URL in the Redirect URL page. If the field is not specified, the default Sign Up URL will be used.

custom_scopes string

Include a space separated list of custom scopes that you'd like to include. Note that this list must be URL encoded, i.e. the spaces must be expressed as %20.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device. See the PKCE OAuth guide for usage instructions.

oauth_attach_token string

A single-use token for connecting the Stytch User selection from an OAuth Attach request to the corresponding OAuth Start request.

Response fields

status_code int

request_id string

redirect_url string

The url to redirect to. This should be done automatically by the browser.

REQUEST

curl \
    --url "https://test.stytch.com/v1/public/oauth/tiktok/start?public_token=PUBLIC_TOKEN&login_redirect_url=https%3A%2F%2Fexample.com%2Flogin&\
signup_redirect_url=https%3A%2F%2Fexample.com%2Fsignup"

RESPONSE

{
    "status_code": 302,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "redirect_url": "https://www.tiktok.com/auth/authorize/?client_key={CLIENT_KEY}&scope=user.info.basic,video.list&response_type=code&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&state=2t6878vioue",
  }

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_urlor signup_redirect_url provided.

Scopes

By default our Twitch OAuth integration includes account and email 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_url string

The URL must be configured as a Login URL in the Redirect URL page. If the field is not specified, the default Login URL will be used.

signup_redirect_url string

The URL must be configured as a Sign Up URL in the Redirect URL page. If the field is not specified, the default Sign Up URL will be used.

custom_scopes string

Include a space separated list of custom scopes that you'd like to include. Note that this list must be URL encoded, i.e. the spaces must be expressed as %20.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device. See the PKCE OAuth guide for usage instructions.

oauth_attach_token string

A single-use token for connecting the Stytch User selection from an OAuth Attach request to the corresponding OAuth Start request.

Response fields

status_code int

request_id string

redirect_url string

The url to redirect to. This should be done automatically by the browser.

REQUEST

curl \
    --url "https://test.stytch.com/v1/public/oauth/twitch/start?public_token=PUBLIC_TOKEN&login_redirect_url=https%3A%2F%2Fexample.com%2Flogin&\
signup_redirect_url=https%3A%2F%2Fexample.com%2Fsignup"

RESPONSE

{
    "status_code": 302,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "redirect_url": "https://twitch.com/api/oauth2/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=identify%3Aemail&state=example-state",
  }

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_urlor signup_redirect_url provided.

Scopes

Twitter scope info coming soon.

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_url string

The URL must be configured as a Login URL in the Redirect URL page. If the field is not specified, the default Login URL will be used.

signup_redirect_url string

The URL must be configured as a Sign Up URL in the Redirect URL page. If the field is not specified, the default Sign Up URL will be used.

custom_scopes string

Include a space separated list of custom scopes that you'd like to include. Note that this list must be URL encoded, i.e. the spaces must be expressed as %20.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device. See the PKCE OAuth guide for usage instructions.

oauth_attach_token string

A single-use token for connecting the Stytch User selection from an OAuth Attach request to the corresponding OAuth Start request.

Response fields

status_code int

request_id string

redirect_url string

The url to redirect to. This should be done automatically by the browser.

REQUEST

curl \
    --url "https://test.stytch.com/v1/public/oauth/twitter/start?public_token=PUBLIC_TOKEN&login_redirect_url=https%3A%2F%2Fexample.com%2Flogin&\
signup_redirect_url=https%3A%2F%2Fexample.com%2Fsignup"

RESPONSE

{
    "status_code": 302,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "redirect_url": "https://twitter.com/i/oauth2/authorize?response_type=code&client_id=M1M5R3BMVy13QmpScXkzTUt5OE46MTpjaQ&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&scope=users.read&state=state&code_challenge=challenge&code_challenge_method=plain",
  }

Authenticate OAuth token

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

The token to authenticate.

session_custom_claims map<string, any>

session_duration_minutes int

(Stytch sessions only) Set the session lifetime to be this many minutes from now. This will start a new session if one doesn't already exist, returning both an opaque session_token and session_jwt for this session. Remember that session_jwt will have a fixed lifetime of five minutes regardless of the underlying session duration, and will need to be refreshed over time.

This argument only sets the lifetime for Stytch sessions, not for IdP sessions. This value must be a minimum of 5 and a maximum of 527040 minutes (366 days).

If a session_token or session_jwt is provided then a successful authentication will continue to extend the session this many minutes.

If the session_duration_minutes parameter is not specified, a Stytch session will not be created.

session_jwt string

(Stytch sessions only) Reuse an existing session instead of creating a new one. If you provide us with a session_jwt, then we'll update the session represented by this JWT with this OAuth factor. If this session_jwt belongs to a different user than the OAuth token, the session_jwt will be ignored. This endpoint will error if both session_token and session_jwt are provided.

session_token string

(Stytch sessions only) Reuse an existing session instead of creating a new one. If you provide us with a session_token, then we'll update the session represented by this session token with this OAuth factor. If this session_token belongs to a different user than the OAuth token, the session_token will be ignored. This endpoint will error if both session_token and session_jwt are provided.

code_verifier string

A base64url encoded one time secret used to validate that the request starts and ends on the same device. See the PKCE OAuth guide for usage instructions.

Response fields

status_code int

request_id string

user_id string

user object

The user object affected by this API call. See the Get user endpoint for complete response field details.

oauth_user_registration_id string

Globally unique UUID that identifies singluar registration of a user with an OAuth identity provider in the Stytch API.

provider_subject string

The provider_subject field is the unique identifier used to identify the user within a given OAuth provider. Also commonly called the "sub" or "Subject field" in OAuth protocols.

provider_type string

The type field denotes the OAuth identity provider that the user has authenticated with, e.g. Google, Facebook, GitHub etc.

provider_values object

The provider_values object lists relevant identifiers, values, and scopes for a given OAuth provider. For example this object will include a provider's access_token that you can use to access the provider's API for a given user.

Note that these values will vary based on the OAuth provider in question, e.g. id_token is only returned by Microsoft.

Collapse

access_token string

The access_token that you may use to access the user's data in the provider's API.

refresh_token string

The refresh_token that you may use to refresh a user's session within the provider's API.

id_token string

The id_token returned by the OAuth provider. This value is similar to an access token but usually may only be used to hit a provider's OIDC endpoint, i.e. login or fetch a session, but not directly interact with the provider's API. See here for more details on how Microsoft treats id_tokens.

scopes array

The OAuth scopes included for a given provider. See each provider's section above to see which scopes are included by default and how to add custom scopes.

reset_sessions boolean

session object

If you initiate a session, by including session_duration_minutes in your authenticate call, you'll receive a full session object in the response.

See GET sessions for complete response fields.

session_token string

A secret token for a given Stytch session. Read more about session_token in our session management guide.

session_jwt string

The JSON Web Token (JWT) for a given Stytch session. Read more about JWTs in our session management guide.

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/oauth/authenticate \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
    "token": "hdPVZHHX0UoRa7hJTuuPHi1vlddffSnoweRbVFf5-H8g",
    "session_duration_minutes": 60
	}'

RESPONSE

{
    "status_code": 200,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
    "user": {...},
    "oauth_user_registration_id": "oauth-user-test-de86770c-911d-463f-80e7-f1b089cead14",
    "provider_subject": "10769150350006150715113082367",
    "provider_type": "Google"
    "provider_values": {
      "access_token": "example-access-token",
      "refresh_token": "example-refresh-token",
      "id_token": "example-id-token",
      "scopes": ["example scope"]
    },
    "reset_sessions": false,
    "session": {
      ...Stytch session...
    },
    "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
    "session_jwt": "example_jwt"
}

Session management overview

Stytch user sessions are identified by a session_token or session_jwtthat 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 project

Query parameters

project_id* string

The project_idto get the JWKS for.

Response fields

status_code int

keys object

The JWK

REQUEST

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

RESPONSE

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

The user ID to get active sessions for.

Response fields

status_code int

request_id string

sessions array[object]

An array of Session objects

REQUEST

curl --request GET \
	--url https://test.stytch.com/v1/sessions \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	--get \
	--data-urlencode 'user_id=user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "sessions": [
    {
      "attributes": {
        "ip_address": "203.0.113.1",
        "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"
      },
      "authentication_factors": [
        {
          "delivery_method": "email",
          "email_factor": {
            "email_address": "sandbox@stytch.com",
            "email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
          },
          "last_authenticated_at": "2021-08-09T07:41:52Z",
          "type": "magic_link"
        }
      ],
      "custom_claims": {
        "claim1": "value1",
        "claim2": "value2",
      },
      "expires_at": "2021-08-10T07:41:52Z",
      "last_accessed_at": "2021-08-09T07:41:52Z",
      "session_id": "session-test-fe6c042b-6286-479f-8a4f-b046a6c46509",
      "started_at": "2021-08-09T07:41:52Z",
      "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
    }
  ],
}

Authenticate 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:09ZThis 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_claims map<string, any>

session_duration_minutes int

Set the session lifetime to be this many minutes from now; minimum of 5 and a maximum of 527040 minutes (366 days). Note that a successful authentication will continue to extend the session this many minutes.

session_jwt string

The JWT to authenticate. You may provide a JWT that has expired according to its exp claim and needs to be refreshed. If the signature is valid and the underlying session is still active then Stytch will return a new JWT.

session_token string

The session token to authenticate.

Response fields

status_code int

request_id string

session object

If you initiate a session, by including session_duration_minutes in your authenticate call, you'll receive a full session object in the response.

See GET sessions for complete response fields.

session_jwt string

The JSON Web Token (JWT) for a given Stytch session. Read more about JWTs in our session management guide.

session_token string

A secret token for a given Stytch session. Read more about session_token in our session management guide.

user object

The user object affected by this API call. See the Get user endpoint for complete response field details.

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/sessions/authenticate \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "session": {
    "attributes": {
      "ip_address": "203.0.113.1",
      "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"
    },
    "authentication_factors": [
      {
        "delivery_method": "email",
        "email_factor": {
          "email_address": "sandbox@stytch.com",
          "email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
        },
        "last_authenticated_at": "2021-08-09T07:41:52Z",
        "type": "magic_link"
      }
    ],
    "custom_claims": {
      "claim1": "value1",
      "claim2": "value2",
    },
    "expires_at": "2021-08-10T07:41:52Z",
    "last_accessed_at": "2021-08-09T07:41:52Z",
    "session_id": "session-test-fe6c042b-6286-479f-8a4f-b046a6c46509",
    "started_at": "2021-08-09T07:41:52Z",
    "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  },
  "session_jwt": "example_jwt"
  "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q"
  "user": {...},
}

Revoke 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_id string

The session ID to revoke.

session_jwt string

A JWT for the session to revoke.

session_token string

The session token to revoke.

Response fields

status_code int

request_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/sessions/revoke \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "session_id": "session-test-fe6c042b-6286-479f-8a4f-b046a6c46509"
	}'

RESPONSE

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

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 register 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_optionswill 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

The user_id of an active user the WebAuthn registration should be tied to.

domain* string

The domain for the WebAuthn registration.

user_agent string

The user_agent of the user.

authenticator_type string

The requested authenticator type of the WebAuthn device. The two valid value are platform and cross-platform. If no value passed, we assume both values are allowed.

Response fields

status_code int

request_id string

user_id string

public_key_credential_creation_options string

Options used for WebAuthn registration.

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/webauthn/register/start \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
	    "domain": "example.com"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "public_key_credential_creation_options": "{\"authenticatorSelection\":{\"userVerification\":\"discouraged\"},\"challenge\":\"hYZtLNT9SIgZqPnKfbnQX3nCJ7NavTT_S6oC9XREYv0F\",\"excludeCredentials\":[],\"pubKeyCredParams\":[{\"alg\":-7,\"type\":\"public-key\"}],\"rp\":{\"id\":\"example.com\",\"name\":\"My First Project\"},\"timeout\":300000,\"user\":{\"displayName\":\"Jane\",\"id\":\"dXNlci10ZXN0LTE2ZDliYTYxLTk3YTEtNGJhNC05NzIwLWIwMzc2MWRjNTBjNg==\",\"name\":\"Jane Doe\"}}"
}

Register WebAuthn registration

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

The user_id the WebAuthn registration is tied to.

public_key_credential* json

The response of the navigator.credentials.create().

Response fields

status_code int

request_id string

user_id string

webauthn_registration_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/webauthn/register \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
	    "public_key_credential": "{\"type\":\"public-key\",\"id\":\"Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlY\",\"rawId\":\"Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlY\",\"response\":{\"clientDataJSON\":\"eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiaFladExOVDlTSWdacVBuS2ZiblFYM25DSjdOYXZUVF9TNm9DOVhSRVl2MEYiLCJvcmlnaW4iOiJodHRwOi8vbG9jYWxob3N0OjMwMDAiLCJjcm9zc09yaWdpbiI6ZmFsc2V9\",\"attestationObject\":\"o2NmbXRmcGFja2VkZ2F0dFN0bXSiY2FsZyZjc2lnWEYwRAIgLEvyXrb_aMCVOjpYBLpm3cPaaquDN0ouXaL27SF9Lp0CIB2f56tWUDvs6oBl3pMxIIrJqJhZKkK7btJtWVDLsFFbaGF1dGhEYXRhWP5Jlg3liA6MaHQ0Fw9kdmBbj-SuuaKGMseZXPO6gx2XY0VheZqwrc4AAjW8xgpkiwsl8fBVAwB6Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlalAQIDJiABIVggFCI-4HODPxlfeBwfFyzQG_btRm_pB6mb9E1E-rANMwoiWCBCr6C2SQOGElh9N9OMzVBcMnOolAcvz3S0STbnNTHOmg\"},\"clientExtensionResults\":{}}"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "webauthn_registration_id": "webauthn-registration-test-5c44cc6a-8af7-48d6-8da7-ea821342f5a6"
}

Start authenticate WebAuthn registration

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_optionswill 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

The user_id of an active user the WebAuthn authentication is for.

domain* string

The domain for the WebAuthn authentication.

Response fields

status_code int

request_id string

user_id string

public_key_credential_request_options string

Options used for WebAuthn authentication.

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/webauthn/authenticate/start \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
	    "domain": "example.com"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "public_key_credential_request_options": "{\"allowCredentials\":[{\"id\":\"AUnfDtA+myCDdumkKnVp2Sk0MIWCPXQVL2mG3h+xQBvLEF+MmNqvj2ZwNIY8id5UHz7ogZKmGgc0mM9yYVhdJNU1n6nIwPBGUuZpr3N18trqXMKxejYYKwCO4BmSHA==\",\"type\":\"public-key\"},],\"challenge\":\"hYZtLNT9SIgZqPnKfbnQX3nCJ7NavTT_S6oC9XREYv0F\",\"rpId\":\"example.com\",\"timeout\":300000,\"userVerification\":\"discouraged\"}"
}

Authenticate WebAuthn registration

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

Complete the authentication of a WebAuthn registration by passing the response from the navigator.credentials.get() request to the authenticate endpoint. If the webauthn-json library's get() method was used, the response can be passed directly to the authenticate endpoint. If not some fields from the navigator.credentials.get() response will need to be converted from array buffers to strings and marshalled into JSON.

Body parameters

public_key_credential* json

The response of the navigator.credentials.get() request.

session_custom_claims map<string, any>

session_duration_minutes int

session_jwt string

Reuse an existing session instead of creating a new one. If you provide us with a session_jwt, then we'll update the session represented by this JWT with this WebAuthn factor. If this session_jwt belongs to a different user than the WebAuthn registration, the session_jwt will be ignored. This endpoint will error if both session_token and session_jwt are provided.

session_token string

Reuse an existing session instead of creating a new one. If you provide us with a session_token, then we'll update the session represented by this session token with this WebAuthn factor. If this session_token belongs to a different user than the WebAuthn registration, the session_token will be ignored. This endpoint will error if both session_token and session_jwt are provided.

Response fields

status_code int

request_id string

session object

If you initiate a session, by including session_duration_minutes in your authenticate call, you'll receive a full session object in the response.

See GET sessions for complete response fields.

session_jwt string

The JSON Web Token (JWT) for a given Stytch session. Read more about JWTs in our session management guide.

session_token string

A secret token for a given Stytch session. Read more about session_token in our session management guide.

user object

The user object affected by this API call. See the Get user endpoint for complete response field details.

user_id string

webauthn_registration_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/webauthn/authenticate \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "public_key_credential": "{\"type\":\"public-key\",\"id\":\"Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlY\",\"rawId\":\"Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlY\",\"response\":{\"authenticatorData\":\"SZYN5YgOjGh7NBcPZHZgW1_krrmihjLHmVzzuoNcl2MFYZKokg\",\"clientDataJSON\":\"eyJ2eXBlOjopo2ViYBx0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiWEtEWDVJa25EWEU3by1KQlRkYTNfS1NiTXdmb3dMWDQxMldlNEFDY04tYWgiLCJvcmlnaW4iOiJodHRwOi8vbG9jYWxob3N0OjMwMDAiLCJjcm9zc09yaWdpbiI6ZmFsc2V9\",\"signature\":\"MEYCIQDU1FGXEBrq3hsQ2ye1pBcYLMu7zmzLVVdcbs6R21hGyAIhAJmpdBo2Hd7P4Ks9VFKBUYbKSIioMdhl2XIIjWHNKD77\",\"userHandle\":\"dXNlus1kZXZlbG9wLBC2M2E1MGI0LWEwMGEtNGU3NC89NTJmLTFlOGRhODE2nDBnMw\"},\"clientExtensionResults\":{}}"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "session": null
  "session_jwt": "",
  "session_token": "",
  "user": {...},
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "webauthn_registration_id": "webauthn-registration-test-5c44cc6a-8af7-48d6-8da7-ea821342f5a6",
}

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 /totps/authenticate 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

The ID of the user to create the TOTP instance for.

expiration_minutes int

The expiration for the TOTP instance. If the newly created TOTP is not authenticated within this time frame the TOTP will be unusable. Defaults to 60 (1 hour) with a minimum of 5 and a maximum of 1440.

Response fields

status_code int

request_id string

secret string

The TOTP secret key shared between the authenticator app and the server used to generate TOTP codes.

totp_id string

qr_code string

The QR code image encoded in base64.

recovery_codes array[string]

The recovery codes used to authenticate the user without an authenticator app.

user_id string

user object

The user object affected by this API call. See the Get user endpoint for complete response field details.

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/totps \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "secret": "BTGNX5RKJRMQWQFRQKTG34JCF6XDRHZS",
  "totp_id": "totp-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c",
  "qr_code": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAAAAADYoy0BAAAG8ElEQVR...8EAAD//7dQP/5Y00bRAAAAAElFTkSuQmCC",
  "recovery_codes": [
    "ckss-2skx-ebow",
    "spbc-424h-usy0",
    "hi08-n5tk-lns5",
    "1n6i-l5na-8axe",
    "aduj-eufq-w6yy",
    "i4l3-dxyt-urmx",
    "ayyi-utb0-gj0s",
    "lz0m-02bi-psbx",
    "l2qm-zrk1-8ujs",
    "c2qd-k7m4-ifmc"
  ]
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "user": {...},
}

Authenticate TOTP

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

Authenticate a TOTP code entered by a user.

Body parameters

user_id* string

The ID of the user the TOTP belongs too.

totp_code* string

The TOTP code to authenticate. The TOTP code should consist of 6 digits.

session_custom_claims map<string, any>

session_duration_minutes int

session_jwt string

Reuse an existing session instead of creating a new one. If you provide us with a session_jwt, then we'll update the session represented by this JWT with this TOTP factor. If this session_jwt belongs to a different user than the TOTP, the session_jwt will be ignored. This endpoint will error if both session_token and session_jwt are provided.

session_token string

Reuse an existing session instead of creating a new one. If you provide us with a session_token, then we'll update the session represented by this session token with this TOTP factor. If this session_token belongs to a different user than the TOTP, the session_token will be ignored. This endpoint will error if both session_token and session_jwt are provided.

Response fields

status_code int

request_id string

totp_id string

session object

If you initiate a session, by including session_duration_minutes in your authenticate call, you'll receive a full session object in the response.

See GET sessions for complete response fields.

session_jwt string

The JSON Web Token (JWT) for a given Stytch session. Read more about JWTs in our session management guide.

session_token string

A secret token for a given Stytch session. Read more about session_token in our session management guide.

user object

The user object affected by this API call. See the Get user endpoint for complete response field details.

user_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/totps/authenticate \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
	    "totp_code": "576831"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "totp_id": "totp-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c",
  "session": null,
  "session_jwt": "",
  "session_token": "",
  "user": {...},
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
}

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

The user_id of the user to fetch TOTP recovery codes for.

Response fields

status_code int

request_id string

user_id string

totps array

The totps array contains a list of all TOTP instances for a given user in the Stytch API, and the associated recovery codes.

Collapse

totp_id string

verified boolean

The verified boolean denotes whether or not this send method, e.g. phone number, email address etc, has been successfully authenticated by the user.

recovery_codes array[string]

An array of recovery codes for the associated TOTP.

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/totps/recovery_codes \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "totps": [
    {
      "totp_id": "totp-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c",
      "verified": true,
      "recovery_codes": [
        "ckss-2skx-ebow",
        "spbc-424h-usy0",
        "hi08-n5tk-lns5",
        "1n6i-l5na-8axe",
        "aduj-eufq-w6yy",
        "i4l3-dxyt-urmx",
        "ayyi-utb0-gj0s",
        "lz0m-02bi-psbx",
        "l2qm-zrk1-8ujs",
        "c2qd-k7m4-ifmc"
      ]
    }
  ]
}

Recover TOTP

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

Authenticate a recovery code for a TOTP instance.

Body parameters

user_id* string

The ID of the user the TOTP belongs too.

recovery_code* string

The recovery code to authenticate.

session_custom_claims map<string, any>

session_duration_minutes int

session_jwt string

Reuse an existing session instead of creating a new one. If you provide us with a session_jwt, then we'll update the session represented by this JWT with this TOTP recovery code factor. If this session_jwt belongs to a different user than the TOTP recovery code, the session_jwt will be ignored. This endpoint will error if both session_token and session_jwt are provided.

session_token string

Reuse an existing session instead of creating a new one. If you provide us with a session_token, then we'll update the session represented by this session token with this TOTP recovery code factor. If this session_token belongs to a different user than the TOTP recovery code, the session_token will be ignored. This endpoint will error if both session_token and session_jwt are provided.

Response fields

status_code int

request_id string

session object

If you initiate a session, by including session_duration_minutes in your authenticate call, you'll receive a full session object in the response.

See GET sessions for complete response fields.

session_jwt string

The JSON Web Token (JWT) for a given Stytch session. Read more about JWTs in our session management guide.

session_token string

A secret token for a given Stytch session. Read more about session_token in our session management guide.

totp_id string

user object

The user object affected by this API call. See the Get user endpoint for complete response field details.

user_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/totps/recover \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
	    "recovery_code": "ckss-2skx-ebow"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "session": null,
  "session_jwt": "",
  "session_token": "",
  "totp_id": "totp-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c"
  "user": {...},
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
}

Crypto wallets 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

The type of wallet to authenticate. Currently ethereum and solana are supported. Wallets for any EVM-compatible chains (such as Polygon or BSC) are also supported and are grouped under the ethereum type.

crypto_wallet_address* string

The address to authenticate.

user_id string

The user_id belonging to the user you wish to associate the address with. If no form of user association is provided and the address is not associated with an existing Stytch user in your Project, a new user will be created.

session_token string

The session_token belonging to the user you wish to associate the address with. If no form of user association is provided and the address is not associated with an existing Stytch user in your Project, a new user will be created.

session_jwt string

The session_jwt belonging to the user you wish to associate the address with. If no form of user association is provided and the address is not associated with an existing Stytch user in your Project, a new user will be created.

Response fields

status_code int

request_id string

user_id string

challenge string

A challenge string to be signed by the wallet in order to prove ownership

user_created boolean

In login_or_create endpoints, this field indicates whether or not a user was freshly created or the user went through a login path.

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/crypto_wallets/authenticate/start \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "crypto_wallet_type": "ethereum",
	    "crypto_wallet_address": "0x6df2dB4Fb3DA35d241901Bd53367770BF03123f1"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "challenge": "Signing in with Project: 7_EPetPqfdEiDCJtgad6-xsXytN3Ee9tx6mdRTQK3fC7-J2PDxpP1GAvYB9Ic4E09h-K88STiRIzKSGP",
  "user_created": true
}

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

The type of wallet to authenticate. Currently ethereum and solana are supported.

crypto_wallet_address* string

The address to authenticate.

signature* string

The signature from the message.

session_custom_claims map<string, any>

session_duration_minutes int

session_jwt string

Reuse an existing session instead of creating a new one. If you provide us with a session_jwt, then we'll update the session represented by this JWT with this crypto wallet factor. If this session_jwt belongs to a different user than the one tied to the address, the session_jwt will be ignored. This endpoint will error if both session_token and session_jwt are provided.

session_token string

Reuse an existing session instead of creating a new one. If you provide us with a session_token, then we'll update the session represented by this session token with this crypto wallet factor. If this session_token belongs to a different user than the one tied to the address, the session_token will be ignored. This endpoint will error if both session_token and session_jwt are provided.

Response fields

status_code int

request_id string

user_id string

user object

The user object affected by this API call. See the Get user endpoint for complete response field details.

session_jwt string

The JSON Web Token (JWT) for a given Stytch session. Read more about JWTs in our session management guide.

session_token string

A secret token for a given Stytch session. Read more about session_token in our session management guide.

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/crypto_wallets/authenticate \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "crypto_wallet_type": "ethereum",
	    "crypto_wallet_address": "0x6df2dB4Fb3DA35d241901Bd53367770BF03123f1",
	    "signature": "0x0c4f82edc3c818b6beff4b89e0682994e5878074609903cecdfb843241728be32f75949e2fbae63dcccdef97c0e3789a26441f7e11456cc1f2ef79b3a436010f1b"
	}'

RESPONSE

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

Password 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

The email of the new user.

password* string

The password for the new user.

session_custom_claims map<string, any>

session_duration_minutes int

Response fields

status_code int

request_id string

user_id string

email_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/passwords \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "email": "sandbox@stytch.com",
	    "password": "O2tp74fb$CixO8x9"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
}

Authenticate user with 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:

The user’s credentials appeared in the HaveIBeenPwned dataset.
1. 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.
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.
1. 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

The email of the user.

password* string

The password of the user.

session_custom_claims map<string, any>

session_duration_minutes int

session_jwt string

Reuse an existing session instead of creating a new one. If you provide us with a session_jwt, then we'll update the session represented by this JWT. If this session_jwt belongs to a different user than the one tied to the address, the session_jwt will be ignored. This endpoint will error if both session_token and session_jwt are provided.

session_token string

Reuse an existing session instead of creating a new one. If you provide us with a session_token, then we'll update the session represented by this session token. If this session_token belongs to a different user than the one tied to the address, the session_token will be ignored. This endpoint will error if both session_token and session_jwt are provided.

Response fields

request_id string

session object

If you initiate a session, by including session_duration_minutes in your authenticate call, you'll receive a full session object in the response.

See GET sessions for complete response fields.

session_jwt string

The JSON Web Token (JWT) for a given Stytch session. Read more about JWTs in our session management guide.

session_token string

A secret token for a given Stytch session. Read more about session_token in our session management guide.

status_code int

user object

The user object affected by this API call. See the Get user endpoint for complete response field details.

user_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/passwords/authenticate \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "email": "sandbox@stytch.com",
	    "password": "O2tp74fb$CixO8x9"
	}'

RESPONSE

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

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

The email of the user that requested the password reset.

reset_password_redirect_url string

The url that the user clicks from the password reset email to finish the reset password flow. This should be a url that your app receives and parses before showing your app's reset password page. After the user submits a new password to your app, it should send an API request to complete the password reset process. If this value is not passed, the default reset password redirect URL that you set in your Dashboard is used. If you have not set a default reset password redirect URL, an error is returned.

login_redirect_url string

The url that the user clicks from the password reset email to skip resetting their password and directly login. This should be a url that your app receives, parses, and subsequently sends an API request to the magic link authenticate endpoint to complete the login process without reseting their password. If this value is not passed, the login redirect URL that you set in your Dashboard is used. If you have not set a default login redirect URL, an error is returned.,

reset_password_expiration_minutes int

Set the expiration for the password reset, in minutes. By default, it expires in 30 minutes. The minimum expiration is 5 minutes and the maximum is 7 days (10080 mins).

reset_password_template_id string

Use a custom template for password reset emails. By default, it will use your default email template. The template must be a template using our built-in customizations or a custom HTML email for Passwords - Password reset.

locale string

attributes object

Provided attributes help with fraud detection. When authenticating a user's token, you can require the IP address and/or the user agent to match that user's attributes when they originated the initial authentication request. To enable this functionality, you can use the options parameter in /v1/passwords/email/reset.

Collapse

ip_address string

The IP address of the user.

user_agent string

The user agent of the user.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device.

Response fields

status_code int

request_id string

user_id string

email_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/passwords/email/reset/start \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "email": "sandbox@stytch.com"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
}

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

The token to authenticate.

password* string

The new password for the user.

options object

Specify optional security settings

Collapse

ip_match_required boolean

Require that the IP address the password reset was requested from matches the IP address it's clicked from.

user_agent_match_required boolean

Require that the user agent the password reset was requested from matches the user agent it's clicked from.

attributes object

Provided attributes help with fraud detection. You can require the IP address and/or the user agent to match the request used to send the password reset using the options parameter.

Collapse

ip_address string

The IP address of the user.

user_agent string

The user agent of the user.

session_custom_claims map<string, any>

session_duration_minutes int

session_jwt string

session_token string

code_verifier string

A base64url encoded one time secret used to validate that the request starts and ends on the same device.

Response fields

status_code int

request_id string

user_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/passwords/email/reset \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "token": "PvC5UudZ7TPZbELt95yXAQ-8MeEUCRob8bUQ-g52fIJs",
	    "password": "O2tp74fb$CixO8x9"
	}'

RESPONSE

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

The user's email.

existing_password* string

The user's existing password.

new_password* string

The new password for the user.

session_custom_claims map<string, any>

session_duration_minutes int

session_jwt string

session_token string

Response fields

status_code int

request_id string

user_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/passwords/existing_password/reset \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "email": "sandbox@stytch.com",
	    "existing_password": "old_password",
	    "new_password": "O2tp74fb$CixO8x9"
	}'

RESPONSE

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

The new password for the user.

session_jwt* string

The session JWT for the user whose password will be reset. This endpoint will error if both session_token and session_jwt are provided.

session_token* string

The session token for the user whose password will be reset. This endpoint will error if both session_token and session_jwt are provided.

Response fields

status_code int

request_id string

user_id string

session object

If you initiate a session, by including session_duration_minutes in your authenticate call, you'll receive a full session object in the response.

See GET sessions for complete response fields.

REQUEST

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

RESPONSE

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

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

The password to strength check.

email string

The email associated with the password. If the email address is included, it will be factored into strength evaluation via our password breach checks. If you do not include the email, it is possible that the strength check response will evaluate as valid – but the password will fail with a weak_password error when used in the Create password endpoint due to a breach check failure.

Response fields

status_code int

request_id string

breach_detection_on_create boolean

Will return true if breach detection will be evaluated. By default this option is enabled. This option can be disabled by contacting support@stytch.com. If this value is false then breached_password will always be false as well.

breached_password boolean

Returns true if the password has been breached. Powered by HaveIBeenPwned.

feedback object

Feedback for how to improve the password's strength using zxcvbn.

Collapse

luds_requirements object

Contains which LUDS properties are fulfilled by the password and which are missing to convert an invalid password into a valid one. You'll use these fields to provide feedback to the user on how to improve the password.

Collapse

has_digit boolean

For LUDS validation, whether the password contains at least one digit.

has_lower_case boolean

For LUDS validation, whether the password contains at least one lowercase letter.

has_symbol boolean

For LUDS validation, whether the password contains at least one symbol. Any UTF8 character outside of a-z or A-Z may count as a valid symbol.

has_upper_case boolean

For LUDS validation, whether the password contains at least one uppercase letter.

missing_characters integer

For LUDS validation, this is the required length of the password that you've set minus the length of the password being checked. The user will need to add this many characters to the password to make it valid.

missing_complexity integer

For LUDS validation, the number of complexity requirements that are missing from the password. Check the complexity fields to see which requirements are missing.

suggestions array

For zxcvbn validation, contains end user consumable suggestions on how to improve the strength of the password.

warning string

For zxcvbn validation, contains an end user consumable warning if the password is valid but not strong enough.

score int

The score of the password determined by zxcvbn. Values will be between 1 and 4, a 3 or greater is required to pass validation.

strength_policy string

The strength policy type enforced, either zxcvbn or luds.

valid_password boolean

Returns true if the password passes our password validation. We offer two validation options, zxcvbn is the default option which offers a high level of sophistication. We also offer LUDS. If an email address is included in the call we also require that the password hasn't been compromised using built-in breach detection powered by HaveIBeenPwned.

REQUEST

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

RESPONSE

{
	"breach_detection_on_create": true,
	"breached_password": false,
	"feedback": {
		"suggestions": null,
		"warning": null,
		"has_digit": true,
		"has_lower_case": false,
		"has_symbol": false,
		"has_upper_case": false,
		"missing_characters": 6,
		"missing_complexity": 1
	},
	"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
	"score": 0,
	"status_code": 200,
	"strength_policy": "luds",
	"valid_password": false
}

Migrate user with password

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

Adds a 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

The email of the user.

hash* string

The password hash. For a Scrypt hash, the hash needs to be a base64 encoded string.

hash_type* string

The password hash used. Currently bcrypt, scrypt, argon2i, argon2id, md_5, and sha_1 are supported.

scrypt_config object

Required parameters if the scrypt is not provided in a PHC encoded form.

Collapse

salt string

The salt value, which should be in a base64 encoded string form.

n_parameter int

The N value, also known as the iterations count. It must be a power of two greater than 1 and less than 262,145. If your applicaiton's N parameter is larger than 262,144, please reach out to support@stytch.com

r_parameter int

The r parameter, also known as the block size.

p_parameter int

The p parameter, also known as the parallelism factor.

key_length int

The key length, also known as the hash length.

argon_2_config object

Required parameters if the argon2 hex form, as opposed to the encoded form, is supplied.

Collapse

salt string

The salt value.

iteration_amount int

The iteration amount.

memory int

The memory in kibibytes.

threads int

The thread value, also known as the parallelism factor.

key_length int

The key length, also known as the hash length.

md_5_config object

Optional parameters for MD-5 hash types.

Collapse

prepend_salt string

The salt that should be prepended to the migrated password.

append_salt string

The salt that should be appended to the migrated password.

sha_1_config object

Optional parameters for SHA-1 hash types.

Collapse

prepend_salt string

The salt that should be prepended to the migrated password.

append_salt string

The salt that should be appended to the migrated password.

Response fields

status_code int

request_id string

user_id string

email_id string

user_created boolean

In login_or_create endpoints, this field indicates whether or not a user was freshly created or the user went through a login path.

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/passwords/migrate \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "email": "sandbox@stytch.com",
	    "hash": "$2a$12$vefoDBbzuMb/NczV/fc9QemTizkNAZr9EO02pIUHPAAJibcYp0.ne",
	    "hash_type": "bcrypt"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
  "user_created": true
}

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.

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.