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.
Explore the details of the Stytch API. Our authentication API is organized around REST principles and has resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Add a user to Stytch. A user_id is returned in the response that can then be used to perform other operations within Stytch. An email or a phone_number is required.
The email to use for email magic links. This can be changed later via the update endpoint.
The phone number to use for one-time passcodes. This can be changed later via the update endpoint. The phone number should be in E.164 format.
The name of the user. Each field in the name object is optional.
Collapse
The first name of the user.
The middle name(s) of the user.
The last name of the user.
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.
Provided attributes help with fraud detection.
Collapse
The IP address of the user.
The user agent of the user.
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.
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.
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.
The user object affected by this API call. See the Get user endpiont for complete response field detail.
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.
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 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.
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.
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 client libraries have convenient helper functions to paginate for you.
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
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".
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
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
The greater_than timestamp specifies the beginning time for this filter, only users created after this timestamp will be returned.
The less_than timestamp specifies the end of this filter, only users created before this timestamp will be returned.
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.
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.
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"].
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.
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".
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}$.
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.
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"].
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.
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"].
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.
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"].
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.
The oauth_provider filter allows you to filter your users based on which OAuth provider they have authenticated with, e.g. ["Google", "Apple"].
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"].
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.
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"].
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.
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"].
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"].
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.
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.
The User searchresults array contains a list of all of the user objects that match your query.
Collapse
The results array contains User objects, see the Get user endpiont for complete response field detail.
The User searchresults_metadata object contains metadata relevant to your specific query like total and next_cursor.
Collapse
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.
The total number of users returned by your query.
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
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": "created_at_between",
"filter_value": {
"greater_than": "2021-12-03T08:58:26Z",
"less_than": "2021-12-18T00:00:00Z"
}
},
{
"filter_name": "phone_number",
"filter_value": ["+12025550162", "+15551112222"]
},
{
"filter_name": "phone_verified",
"filter_value": true
},
{
"filter_name": "status",
"filter_value": "active"
},
{
"filter_name": "full_name_fuzzy",
"filter_value": "Grace"
}
]
}
}'
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
}
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
The user_id for the user to fetch.
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.
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.
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.
The name object contains three values: first_name,middle_name,last_name.
The emails object contains an array of email objects for the user.
Collapse
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.
The email address.
The verified boolean denotes whether or not this send method, e.g. phone number, email address etc, has been successfully authenticated by the user.
The phone_numbers array contains an array of phone number objects for the user.
Collapse
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.
A phone number.
The verified boolean denotes whether or not this send method, e.g. phone number, email address etc, has been successfully authenticated by the user.
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
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.
The type field denotes the OAuth identity provider that the user has authenticated with, e.g. Google, Facebook, GitHub etc.
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.
If available, the locale is the user's locale set in the OAuth identity provider that the user has authenticated with.
The webauthn_registrations array contains a list of all WebAuthn registrations for a given user in the Stytch API.
Collapse
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.
The domain on which a WebAuthn registration was started. This will be the domain of your app.
The user_agent of the user's browser or device.
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.
The verified boolean denotes whether or not this send method, e.g. phone number, email address etc, has been successfully authenticated by the user.
The totps array contains a list of all TOTP instances for a given user in the Stytch API.
Collapse
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.
The verified boolean denotes whether or not this send method, e.g. phone number, email address etc, has been successfully authenticated by the user.
The crypto_wallets array contains a list of all crypto wallets that a user has linked via Stytch.
Collapse
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.
The crypto_wallet_address is the actual blockchain address of this user's crypto wallet.
The crypto_wallet_type is the blockchain that the user's crypto wallet operates on, e.g. Ethereum, Solana, etc.
The verified boolean denotes whether or not this send method, e.g. phone number, email address etc, has been successfully authenticated by the user.
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.
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"
},
"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": [
{
"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
}
],
"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
}
],
"created_at": "2021-11-14T21:30:23Z",
"status": "active"
}
Update a user's attributes. For example, you can add additional emails or change the user's name.
Path parameters
The user_id to update.
The name of the user. If at least one name field is passed, all name fields will be updated.
Collapse
The first name of the user. Replaces an existing first name, if it exists.
The middle name(s) of the user. Replaces an existing middle name, if it exists.
The last name of the user. Replaces an existing last name, if it exists.
Multiple emails can exist for one user. Add additional emails via this endpoint. To delete an email, use the delete user email endpoint.
Collapse
An email for the user.
Multiple phone numbers can exist for one user. Add additional phone numbers via this endpoint. To delete a phone number, use the delete user phone number endpoint.
Collapse
A phone number for the user. The phone number should be in E.164 format.
Multiple crypto wallets can exist for a single user. You may add crypto wallets to a Stytch user via this endpoint, this endpoint accepts a list of crypto objects, i.e. a set of crypto_wallet_addresss and crypto_wallet_types.
To delete a crypto wallet, use the /users/crypto_wallets/CRYPTO_WALLET_ID endpoint.
Collapse
A crypto wallet address.
A crypto wallet type.
Provided attributes help with fraud detection.
Collapse
The IP address of the user.
The user agent of the user.
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.
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.
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.
The user object affected by this API call. See the Get user endpiont for complete response field detail.
The name object contains three values: first_name,middle_name,last_name.
The emails object contains an array of email objects for the user.
Collapse
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.
The email address.
The verified boolean denotes whether or not this send method, e.g. phone number, email address etc, has been successfully authenticated by the user.
The phone_numbers array contains an array of phone number objects for the user.
Collapse
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.
A phone number.
The verified boolean denotes whether or not this send method, e.g. phone number, email address etc, has been successfully authenticated by the user.
The crypto_wallets array contains a list of all crypto wallets that a user has linked via Stytch.
Collapse
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.
The crypto_wallet_address is the actual blockchain address of this user's crypto wallet.
The crypto_wallet_type is the blockchain that the user's crypto wallet operates on, e.g. Ethereum, Solana, etc.
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"
}
}'
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": {...}
}
Remove a user from Stytch.
Path parameters
The user_id to be deleted.
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.
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.
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.
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"
}
Remove an email from a given user.
Path parameters
The email_id to be deleted.
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.
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.
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.
The user object affected by this API call. See the Get user endpiont for complete response field detail.
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": {...}
}
Remove a phone number from a given user.
Path parameters
The phone_id to be deleted.
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.
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.
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.
The user object affected by this API call. See the Get user endpiont for complete response field detail.
REQUEST
curl --request DELETE \
--url https://test.stytch.com/v1/users/phone_numbers/phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json'
RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user": {...}
}
Delete a previously created WebAuthn registration.
Path parameters
The webauthn_registration_id to be deleted.
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.
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.
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.
The user object affected by this API call. See the Get user endpiont for complete response field detail.
REQUEST
curl --request DELETE \
--url https://test.stytch.com/v1/users/webauthn_registrations/webauthn-registration-test-5c44cc6a-8af7-48d6-8da7-ea821342f5a6 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json'
RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user", {...}
}
Delete a previously created TOTP instance.
Path parameters
The totp_id to be deleted.
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.
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.
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.
The user object affected by this API call. See the Get user endpiont for complete response field detail.
REQUEST
curl --request DELETE \
--url https://test.stytch.com/v1/users/totps/totp-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json'
RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user": {...}
}
Delete a crypto wallet.
Path parameters
The crypto_wallet_id to be deleted.
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.
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.
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.
The user object affected by this API call. See the Get user endpiont for complete response field detail.
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": {...}
}
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.
The maximum number of users to be returned per API call.
The user ID to start after.
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
}
],
"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 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.
The email of the user to send the invite magic link to.
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.
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.
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).
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).
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
The IP address of the user.
The user agent of the user.
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.
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.
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.
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.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/magic_links/email/send \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "sandbox@stytch.com"
}'
RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
}
Send either a login or signup magic link to the user based on if the email is associated with a user already. A new or pending user will receive a signup magic link. An active user will receive a login magic link. For more information on how to control the status your users are created in see the create_user_as_pending flag.
The email of the user to send the invite magic link to.
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.
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.
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).
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).
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.
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
The IP address of the user.
The user agent of the user.
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.
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.
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.
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.
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
}
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.
The email of the user to send the invite magic link to.
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.
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).
The name of the user. Each field in the name object is optional.
Collapse
The first name of the user.
The middle name(s) of the user.
The last name of the user.
Provided attributes help with fraud detection.
Collapse
The IP address of the user.
The user agent of the user.
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.
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.
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.
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.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/magic_links/email/invite \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "sandbox@stytch.com"
}'
RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
}
Revoke a pending invite based on the email provided.
The email of the user to revoke invite for.
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.
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.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/magic_links/email/revoke_invite \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "sandbox@stytch.com"
}'
RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141"
}
With our out-of-the-box email magic links product, Stytch is able to fully handle the frustrating and complex pieces of email deliverability, latency, and inbox placement. However, we also offer a flexible way for you to embed magic links into any use case you can imagine. For example, you could send magic links from your own domain, embed them into customized templates, or leverage different communication channels, like sms, to send them. By using our magic link create endpoint, you can embed magic links into all of your end-user communications to reduce friction and improve conversion. If needed, you can always add more authentication requirements to a user’s session to improve security by using the rest of Stytch’s product suite.
Create 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.
The user ID for the magic link token.
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).
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
The IP address of the user.
The user agent of the user.
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.
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.
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.
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 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.
The token to authenticate.
Specify optional security settings
Collapse
Require that the IP address the magic link was requested from matches the IP address it's clicked from.
Require that the user agent the magic link was requested from matches the user agent it's clicked from.
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
The IP address of the user.
The user agent of the user.
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 129600 minutes (90 days).
If a session_token or session_jwt is provided then a successful authentication will continue to extend the session this many minutes.
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.
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.
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.
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.
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.
The user object affected by this API call. See the Get user endpiont for complete response field detail.
The JSON Web Token (JWT) for a given Stytch session. Read more about JWTs in our session management guide.
A secret token for a given Stytch session. Read more about session_token in our session management guide.
Globally unique UUID that identifies a specific session in the Stytch API. The session_id is used when you need to operate on a specific user's session, e.g. to revoke the session, refresh it, etc.
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
{
"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": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
"session_jwt": "",
"session_token": "",
"session": null
}
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 a one-time passcode to a user 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.
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.
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.
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
The IP address of the user.
The user agent of the user.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/otps/sms/send \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"phone_number": "+12025550162"
}'
RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"phone_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0"
}
Send a one-time passcode to a user using their phone number. If the phone number is not associated with a user already, a user will be created.
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.
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.
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.
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
The IP address of the user.
The user agent of the user.
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"
}
Send a one-time passcode 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.
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.
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.
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
The IP address of the user.
The user agent of the user.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/otps/whatsapp/send \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"phone_number": "+12025550162"
}'
RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"phone_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0"
}
Send a one-time passcode 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.
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.
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.
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.
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
The IP address of the user.
The user agent of the user.
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"
}
Email passcodes sends a one-time passcode (OTP) to the user's email. The user will then submit that code to your app.
Send a one-time passcode 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.
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.
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.
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
The IP address of the user.
The user agent of the user.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/otps/email/send \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "sandbox@stytch.com"
}'
RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
}
Send a one-time passcode to a user using their email. If the email is not associated with a user already, a user will be created.
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.
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.
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.
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
The IP address of the user.
The user agent of the user.
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.
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.
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.
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.
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"
}
Authenticate a user given a method 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.
The ID of the method used to send a one-time passcode.
The code to authenticate.
Specify optional security settings
Collapse
Require that the IP address the one-time passcode was requested from matches the IP address upon code entry.
Require that the user agent the one-time passcode was requested from matches the user agent upon code entry.
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
The IP address of the user.
The user agent of the user.
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 129600 minutes (90 days).
If a session_token or session_jwt is provided then a successful authentication will continue to extend the session this many minutes.
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.
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.
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",
"session_jwt": "",
"session_token": "",
"session": null
}
OAuth is a popular authentication framework that delegates authentication to an external identity provider (often shortened to IdP) like Google, Facebook, Apple, and Microsoft. A user relies on their membership from that provider to sign in instead of creating another password, and developers can enrich their users' experiences with the information shared by the providers. While OAuth has many benefits, developers need to understand the OAuth framework well to implement it securely. Stytch's OAuth product simplifies the process by abstracting the implementation details of OAuth for developers. The steps for an OAuth flow are simple:
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.
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.
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.
The URL that Stytch redirects to after the OAuth flow is completed for a user that already exists. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Login URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
The URL that Stytch redirects to after the OAuth flow is completed for a user that does not yet exist. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Sign Up URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
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.
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.
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",
}
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.
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.
The URL that Stytch redirects to after the OAuth flow is completed for a user that already exists. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Login URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
The URL that Stytch redirects to after the OAuth flow is completed for a user that does not yet exist. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Sign Up URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
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.
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.
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",
}
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.
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.
The URL that Stytch redirects to after the OAuth flow is completed for a user that already exists. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Login URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
The URL that Stytch redirects to after the OAuth flow is completed for a user that does not yet exist. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Sign Up URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
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.
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.
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",
}
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.
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.
The URL that Stytch redirects to after the OAuth flow is completed for a user that already exists. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Login URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
The URL that Stytch redirects to after the OAuth flow is completed for a user that does not yet exist. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Sign Up URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
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.
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.
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",
}
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.
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.
The URL that Stytch redirects to after the OAuth flow is completed for a user that already exists. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Login URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
The URL that Stytch redirects to after the OAuth flow is completed for a user that does not yet exist. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Sign Up URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
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.
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.
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",
}
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.
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.
The URL that Stytch redirects to after the OAuth flow is completed for a user that already exists. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Login URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
The URL that Stytch redirects to after the OAuth flow is completed for a user that does not yet exist. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Sign Up URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
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.
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.
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",
}
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.
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.
The URL that Stytch redirects to after the OAuth flow is completed for a user that already exists. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Login URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
The URL that Stytch redirects to after the OAuth flow is completed for a user that does not yet exist. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Sign Up URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
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.
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.
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",
}
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.
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.
The URL that Stytch redirects to after the OAuth flow is completed for a user that already exists. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Login URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
The URL that Stytch redirects to after the OAuth flow is completed for a user that does not yet exist. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Sign Up URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
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.
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.
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",
}
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.
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.
The URL that Stytch redirects to after the OAuth flow is completed for a user that already exists. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Login URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
The URL that Stytch redirects to after the OAuth flow is completed for a user that does not yet exist. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Sign Up URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
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.
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.
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",
}
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.
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.
The URL that Stytch redirects to after the OAuth flow is completed for a user that already exists. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Login URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
The URL that Stytch redirects to after the OAuth flow is completed for a user that does not yet exist. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Sign Up URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
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.
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.
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",
}
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.
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.
The URL that Stytch redirects to after the OAuth flow is completed for a user that already exists. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Login URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
The URL that Stytch redirects to after the OAuth flow is completed for a user that does not yet exist. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's /oauth/authenticate endpoint and finishes the login. The URL should be configured as a Sign Up URL in the Stytch Dashboard's Redirect URL page. If the field is not specified, the default in the Dashboard is used.
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.
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.
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",
}
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.
The token to authenticate.
(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 129600 minutes (90 days).
If a session_token or session_jwt is provided then a successful authentication will continue to extend the session this many minutes.
(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.
(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.
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.
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.
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.
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.
The user object affected by this API call. See the Get user endpiont for complete response field detail.
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.
The type field denotes the OAuth identity provider that the user has authenticated with, e.g. Google, Facebook, GitHub etc.
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
The access_token that you may use to access the user's data in the provider's API.
The refresh_token that you may use to refresh a user's session within the provider's API.
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.
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.
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.
A secret token for a given Stytch session. Read more about session_token in our session management guide.
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": {...},
"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"]
},
"session": {
...Stytch session...
},
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
"session_jwt": "example_jwt"
}
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 the JSON Web Key Set (JWKS) for a project
The project_idto get the JWKS for.
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",
},
],
}
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.
The user ID to get active sessions for.
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"
}
],
"expires_at": "2021-08-10T07:41:52Z",
"last_accessed_at": "2021-08-09T07:41:52Z",
"session_id": "session-test-fe6c042b-6286-479f-8a4f-b046a6c46509",
"started_at": "2021-08-09T07:41:52Z",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
}
],
}
Authenticate a session token and retrieve associated session data. If session_duration_minutes is included, update the lifetime of the session to be that many minutes from now. All timestamps are formatted according to the RFC 3339 standard and are expressed in UTC, e.g. 2021-12-29T12:33: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.
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.
The session token to authenticate.
Set the session lifetime to be this many minutes from now; minimum of 5 and a maximum of 129600 minutes (90 days). Note that a successful authentication will continue to extend the session this many minutes.
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"
}
],
"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",
},
"user": {...},
"session_jwt": "example_jwt"
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q"
}
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.
The session ID to revoke.
A JWT for the session to revoke.
The session token to revoke.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/sessions/revoke \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"session_id": "session-test-fe6c042b-6286-479f-8a4f-b046a6c46509"
}'
RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141"
}
The Web Authentication API (WebAuthn) is a specification that allows web applications on supported browsers to authenticate a user via authenticator types such as built-in device biometrics (e.g. facial recognition on mobile and fingerprint readers on desktop) or secure hardware keys (e.g. YubiKeys). While WebAuthn has many benefits, developers need to understand the API to implement it securely. Stytch's WebAuthn product simplifies the process by abstracting the implementation details of WebAuthn for developers to make it as quick as possible to implement securely.
There are two steps during a WebAuthn authentication flow, registration and authentication. The first step handles registering a WebAuthn device to a user. The second step handles the authentication attempt.
For both the registration and authentication steps, you’ll make two Stytch requests. The first request returns the necessary components to communicate with the WebAuthn device. The second request is used to pass the response from the WebAuthn call back to Stytch for verification.
You can read an in depth guide here.
Initiate the process of creating a new WebAuthn registration. After calling this endpoint, the browser will need to call navigator.credentials.create() with the data from public_key_credential_creation_options passed to the navigator.credentials.create() request via the public key argument. We recommend using the create()wrapper provided by the webauthn-json library. If you are not using the webauthn-json library, the public_key_credential_creation_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.
The user_id of an active user the WebAuthn registration should be tied to.
The domain for the WebAuthn registration.
The user_agent of the user.
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.
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\"}}"
}
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.
The user_id the WebAuthn registration is tied to.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/webauthn/register \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"public_key_credential": "{\"type\":\"public-key\",\"id\":\"Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlY\",\"rawId\":\"Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlY\",\"response\":{\"clientDataJSON\":\"eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiaFladExOVDlTSWdacVBuS2ZiblFYM25DSjdOYXZUVF9TNm9DOVhSRVl2MEYiLCJvcmlnaW4iOiJodHRwOi8vbG9jYWxob3N0OjMwMDAiLCJjcm9zc09yaWdpbiI6ZmFsc2V9\",\"attestationObject\":\"o2NmbXRmcGFja2VkZ2F0dFN0bXSiY2FsZyZjc2lnWEYwRAIgLEvyXrb_aMCVOjpYBLpm3cPaaquDN0ouXaL27SF9Lp0CIB2f56tWUDvs6oBl3pMxIIrJqJhZKkK7btJtWVDLsFFbaGF1dGhEYXRhWP5Jlg3liA6MaHQ0Fw9kdmBbj-SuuaKGMseZXPO6gx2XY0VheZqwrc4AAjW8xgpkiwsl8fBVAwB6Ab6y28pCs5bVRIzSmrlufidfR57gRlEZ-KSTVGJYdkwAfR_SeaVXvdW6ND_XljM25cXYI-dSwrhjuNsj1L3uC0BHqN3mBQIzSswJneTv08RbDNZOLhjiwOEnQ03uPbL5eA7EcyinClOU_qwPMf5lowW1NSTWtaFvOlalAQIDJiABIVggFCI-4HODPxlfeBwfFyzQG_btRm_pB6mb9E1E-rANMwoiWCBCr6C2SQOGElh9N9OMzVBcMnOolAcvz3S0STbnNTHOmg\"},\"clientExtensionResults\":{}}"
}'
RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"webauthn_registration_id": "webauthn-registration-test-5c44cc6a-8af7-48d6-8da7-ea821342f5a6"
}
Initiate the authentication of a WebAuthn registration. After calling this endpoint, the browser will need to call navigator.credentials.get() with the data from public_key_credential_request_options passed to the navigator.credentials.get() request via the public key argument. We recommend using the get()wrapper provided by the webauthn-json library. If you are not using the webauthn-json library, the public_key_credential_request_optionswill need to be converted to a suitable public key by unmarshalling the JSON and converting some the fields to array buffers.
The user_id of an active user the WebAuthn authentication is for.
The domain for the 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\"}"
}
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.
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 129600 minutes (90 days).
If a session_token or session_jwt is provided then a successful authentication will continue to extend the session this many minutes.
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.
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.
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",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user": {...},
"webauthn_registration_id": "webauthn-registration-test-5c44cc6a-8af7-48d6-8da7-ea821342f5a6",
"session_jwt": "",
"session_token": "",
"session": null
}
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 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.
The ID of the user to create the TOTP instance for.
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.
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"
]
}
Authenticate a TOTP code entered by a user.
The ID of the user the TOTP belongs too.
The TOTP code to authenticate. The TOTP code should consist of 6 digits.
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 129600 minutes (90 days).
If a session_token or session_jwt is provided then a successful authentication will continue to extend the session this many minutes.
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.
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.
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",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user": {...},
"totp_id": "totp-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c",
"session_jwt": "",
"session_token": "",
"session": null
}
Retrieve the recovery codes for a TOTP instance tied to a user.
The user_id of the user to fetch TOTP recovery codes for.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/totps/recovery_codes \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
}'
RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"totps": [
{
"totp_id": "totp-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c",
"verified": true,
"recovery_codes": [
"ckss-2skx-ebow",
"spbc-424h-usy0",
"hi08-n5tk-lns5",
"1n6i-l5na-8axe",
"aduj-eufq-w6yy",
"i4l3-dxyt-urmx",
"ayyi-utb0-gj0s",
"lz0m-02bi-psbx",
"l2qm-zrk1-8ujs",
"c2qd-k7m4-ifmc"
]
}
]
}
Authenticate a recovery code for a TOTP instance.
The ID of the user the TOTP belongs too.
The recovery code to authenticate.
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 129600 minutes (90 days).
If a session_token or session_jwt is provided then a successful authentication will continue to extend the session this many minutes.
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.
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.
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_jwt": "",
"session_token": "",
"session": null,
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user": {...},
"totp_id": "totp-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c"
}
Crypto wallets allow users to hold digital assets, like cryptocurrencies and NFTs, and easily cryptographically authenticate themselves on a blockchain. Our Crypto wallets product allows your users to seamlessly authenticate to your application via MetaMask, Phantom, or any other Ethereum or Solana based crypto wallets. Unlock Web3 via Stytch without having to touch a blockchain.
Initiate the authentication of a crypto wallet. After calling this endpoint, the user will need to sign a message containing only the returned challenge field.
The type of wallet to authenticate. Currently ethereum and solana are supported.
The address to authenticate.
The user_id to associate the address with. If no user_id is provided and the address is not associated with an existing Stytch user in your Project, a new user will be created.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/crypto_wallets/authenticate/start \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"crypto_wallet_type": "ethereum",
"crypto_wallet_address": "0x6df2dB4Fb3DA35d241901Bd53367770BF03123f1"
}'
RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"challenge": "Signing in with Project: 7_EPetPqfdEiDCJtgad6-xsXytN3Ee9tx6mdRTQK3fC7-J2PDxpP1GAvYB9Ic4E09h-K88STiRIzKSGP",
"user_created": true
}
Complete the authentication of a crypto wallet by passing the signature.
The type of wallet to authenticate. Currently ethereum and solana are supported.
The address to authenticate.
The signature from the message.
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 129600 minutes (90 days).
If a session_token or session_jwt is provided then a successful authentication will continue to extend the session this many minutes.
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.
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.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/crypto_wallets/authenticate \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"crypto_wallet_type": "ethereum",
"crypto_wallet_address": "0x6df2dB4Fb3DA35d241901Bd53367770BF03123f1",
"signature": "0x0c4f82edc3c818b6beff4b89e0682994e5878074609903cecdfb843241728be32f75949e2fbae63dcccdef97c0e3789a26441f7e11456cc1f2ef79b3a436010f1b"
}'
RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"user": {...},
"session_jwt": "",
"session_token": ""
}
Stytch supports creating, storing, and authenticating password based users,
as well as support for account recovery (password reset) and account deduplication
with passwordless login methods.
For migrating existing password based users into Stytch, we will support importing
bcrypt, scrypt, argon2, MD-5 and SHA-1 password hashes from common auth providers
like Cognito, Auth0, and Firebase.
Our implementation of passwords has built-in breach detection powered by HaveIBeenPwned on both sign-up and login, to prevent the use of compromised credentials and uses Dropbox’s zxcvbn strength requirements to guide users towards creating passwords that
are easy for humans to remember but difficult for computers to crack.
Create a new user with a password and an authenticated session for the user if requested. If a user with this
email already exists in the project, this API will return an error.
Existing passwordless users who wish to
create a password need to go through the reset password flow.
This endpoint will return an error if the
password provided does not meet our strength requirements, which you can check beforehand with the password
strength endpoint.
The email of the new user.
The password for the new user.
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 129600 minutes (90 days).
If a session_token or session_jwt is provided then a successful authentication will continue to extend the session this many minutes.
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": "jvx-kbj4nbj7ZKP9ncv"
}'
RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
}
Authenticate a user with their email address and password.
This endpoint verifies that the user has a password currently set, and that the entered password is correct.
There are two instances where the endpoint will return a reset_password error even if they enter their previous password:
The email of the user.
The password of the user.
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 129600 minutes (90 days).
If a session_token or session_jwt is provided then a successful authentication will continue to extend the session this many minutes.
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.
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.
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": "jvx-kbj4nbj7ZKP9ncv"
}'
RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
}
Initiates a password reset for the email address provided. This will trigger an email to be sent to the address, containing a magic link that will allow them to set a new password and authenticate.
The email of the user that requested the password reset.
The url the user clicks from the password reset email. This should be a url that your app receives and parses and subsequently 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.
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).
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
The IP address of the user.
The user agent of the user.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/passwords/email/reset/start \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email": "sandbox@stytch.com"
}'
RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
}
Reset the user’s password and authenticate them. This endpoint checks that the magic link token is valid, hasn’t expired, or already been used – and can optionally require additional security settings, such as the IP
address and user agent matching the initial reset request.
The provided password needs to meet our password
strength requirements, which can be checked in advance with the password strength endpoint. If the token and
password are accepted, the password is securely stored for future authentication and the user is
authenticated.
The token to authenticate.
The new password for the user.
Specify optional security settings
Collapse
Require that the IP address the password reset was requested from matches the IP address it's clicked from.
Require that the user agent the password reset was requested from matches the user agent it's clicked from.
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
The IP address of the user.
The user agent of the user.
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 129600 minutes (90 days).
If a session_token or session_jwt is provided then a successful authentication will continue to extend the session this many minutes.
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.
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.
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": "jvx-kbj4nbj7ZKP9ncv"
}'
RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
}
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.
Passwords are considered invalid if either of the following is true:
The password to strength check.
The email assoicated with the password. Provide this for a more acurate strength check.
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.
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.
States whether the password passes our password validation. Our validation requires a 3 or higher score that's calculated using zxcvbn. We also require that the password hasn't been pwned using built-in breach detection powered 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": "jvx-kbj4nbj7ZKP9ncv"
}'
RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"valid_password": true,
"score": 4,
"breached_password": false,
"feedback": {
"suggestions": [],
"warning": ""
}
}
Learn more about Stytch concepts, data models, and general API concerns.
The Stytch API uses basic authentication for all API requests. The username will be your project_id and the password will be your secret. You can retrieve both your test and live API keys from the developer dashboard.
There are two environments, TEST and LIVE, each with unique API keys and urls, test.stytch.com and api.stytch.com. Additionally, the resources created in each environment are tied to the environment they were created in. The ids used for objects include the environment they are tried to, for example user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6.
Email templates control the subject line and body of the email a user receives. For Magic Link endpoints that send emails, there are three possible email templates a user can receive: login, signup or invite. Which email template a user receives is based on a combination of the user's state in the Stytch backend and the endpoint used.
You can use the official Stytch Postman collection to test and learn about the Stytch API before writing any code. The workspace includes requests for all of Stytch's API endpoints. Find it here!
To ensure your users are always routed to the correct place, Stytch verifies any redirect URLs provided in requests against redirect URLs that are configured in the developer dashboard. For each redirect URL type (login, signup or invite), a developer can specify one or more URLs for each type. Each project also has separate redirect URLs for the test and live environments. When verifying the redirect URL from the request against the predefined URLs for the project, Stytch looks for an exact match, including any subdirectories and query parameters. Please visit the dashboard to set redirect URLs for your project.
A user's state impacts how they are treated within Stytch, in particular which email template they are sent. Users within Stytch can be in three different states: pending, active, or deleted.
Stytch uses HTTP response status codes to indicate the success or failure of your API requests. For failures, Stytch returns an error using the appropriate status code. There are three categories for status codes:
4xx errors generally require some action to be taken to resolve them. Below is a list of possible error codes that can be returned, along with additional information about how to resolve them. These types of errors also include the url attribute with a direct link to the specific error code it corresponds to.
active_totp_exists: Cannot create a new TOTP for the specified user since the user already has an active TOTP. Users may only have one active TOTP at a time.
bad_request: The submitted request is invalid.
billing_not_verified: You cannot use this endpoint in the live environment until credit card details are added to your account, but you can try the endpoint in the test environment. Once your billing information is verified, this endpoint can be used in live. Your first 100 monthly active users are always free but collecting this information helps us prevent abuse of the platform. Please see billing settings to provide billing information.
billing_not_verified_for_email: You can only send magic links to emails matching your project's domain until credit card details are added to your account. Once your billing information is verified, emails can be sent to anyone. Your first 100 monthly active users are always free but collecting this information helps us prevent abuse of the platform. Please see billing settings to provide billing information.
cannot_use_webauthn_with_pending_user: WebAuthn can only be used with active users. To learn more about WebAuthn and user states please see here and here.
duplicate_wallet_address: A user with the specified crypto wallet address already exists for this project.
duplicate_wallet_address_for_user: The specified crypto wallet address is already tied to this user.
duplicate_email: The email provided is a duplicate. The email is already tied to a user for the provided project.
duplicate_email_for_user: The email provided is already tied to the user provided.
duplicate_phone_number: The phone number provided is a duplicate. The phone number is already tied to a user for the provided project.
duplicate_phone_number_for_user: The phone number provided is already tied to the user provided.
duplicate_webauthn_registration: The supplied credential ID already exists for this project.
expired_totp: The TOTP for this user has expired without being verified.
inactive_email: The provided email is inactive. The email has been marked as inactive by our email provider. This most often happens when the email is undeliverable due to a prior hard bounce.
incompatible_session_type: Session token and session duration are arguments for Stytch sessions. Leave these arguments blank when using IDP sessions.
invalid_authorization_header: The authorization header provided with the request is invalid.
invalid_authentication_type: The authentication type provided in the header of the request is invalid. The Stytch API uses basic authentication. See more about authenticating Stytch API requests here.
invalid_authenticator_type: Invalid authenticator type. The valid values are platform and cross-platform.
invalid_code: The code is invalid (e.g., not properly formatted) or missing. Ensure the code is six digits.
invalid_create_user_request: Please provide either an email or phone_number in the CreateUser request.
invalid_crypto_wallet_id: The crypto_wallet_id is invalid (i.e. not properly formatted) or missing. crypto-wallet-test-dbbd372e-79f8-48ea-907c-5f0755e7d328 is an example crypto_wallet_id.
invalid_domain: Invalid domain, ensure that only the domain was provided. Do not include https:// or a port in this value. Visit the link here for more information about valid domains (called RP ID on the site).
invalid_email: The email address is invalid (i.e. not properly formatted) or missing. Check that the email address is properly formatted and only includes allowed characters.
invalid_ethereum_address: The crypto_wallet_address format is invalid for an Ethereum address. Expecting a string starting with 0x followed by 40 hexadecimal characters.
invalid_email_id: The email_id is invalid (i.e. not properly formatted) or missing. email-test-81bf03a8-86e1-4d95-bd44-bb3495224953 is an example email_id.
invalid_expiration: The expiration_minutes is invalid (i.e. not properly formatted) or missing. Make sure the value provided is between 5 and 10080 minutes.
invalid_expiration_otp: The expiration_minutes is invalid (i.e. not properly formatted) or missing. Make sure the value provided is between 1 and 10 minutes.
invalid_invite_magic_link_url: The invite_magic_link_url is invalid (i.e. not properly formatted) or missing.
invalid_ip_address: The ip_address is invalid (i.e. not properly formatted) or missing.
invalid_login_magic_link_url: The login_magic_link_url is invalid (i.e. not properly formatted) or missing.
invalid_magic_link_url: The magic_link_url is invalid (i.e. not properly formatted) or missing.
invalid_method_id: The method_id is invalid (i.e. not properly formatted) or missing. email-test-81bf03a8-86e1-4d95-bd44-bb3495224953 is an example method_id.
invalid_phone_number: The phone number is invalid (i.e. not properly formatted) or missing. Check that the phone number is properly formatted with the E. 164 format and only includes allowed characters.
invalid_phone_number_country_code: The phone number's country code is invalid or not supported. Stytch does not support sending SMS passcodes to the following countries:
Please reach out to support@stytch.com if you have any questions.
invalid_project_id_authentication: The project ID provided in the basic authentication header is invalid. Please check to make sure the format is correct and there are no trailing whitespaces. To view your project ID please visit the Stytch dashboard here.
invalid_public_key_credential: Invalid public key credential. Please confirm you're passing a correctly formatted public key credential.
invalid_recovery_code: The recovery_code submitted was invalid.
invalid_secret_authentication: The secret provided in the basic authentication header is invalid. Please check to make sure the format is correct and there are no trailing whitespaces. To create a new secret for your project or to confirm an existing secret please visit the Stytch dashboard here.
invalid_session_id: The session_id format is invalid (i.e. not properly formatted).
invalid_session_token: The session_token format is invalid (i.e. not properly formatted).
invalid_session_token_docs: The session token you provided is a sample one from the docs. Please use a session token that you received from an authenticate request.
invalid_signature: The signature is invalid.
invalid_signup_magic_link_url: The signup_magic_link_url is invalid (i.e. not properly formatted) or missing.
invalid_solana_address: The crypto_wallet_address format is invalid for an Solana address. Expecting a 32 or 44 character base58 string.
invalid_token: The token is invalid (i.e. not properly formatted) or missing.
invalid_totp_code: The format of the totp_code submitted was invalid. The totp_code must be 6 digits long.
invalid_totp_id: totp_id format is invalid (i.e. not properly formatted).
invalid_user_agent: The user_agent is invalid (i.e. not properly formatted) or missing.
invalid_user_id: The user_id is invalid (i.e. not properly formatted) or missing. user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6 is an example user_id.
invalid_wallet_type: The crypto_wallet_type is invalid.
invalid_wallet_address_user: The passed crypto_wallet_address belongs to a different user than the user_id provided.
invalid_webauthn_domain: A WebAuthn domain cannot be longer than 255 characters, please verify that you're passing in a valid domain.
live_id_used_in_test_environment: Invalid argument sent to Test environment. An ID associated with the Live environment (api.stytch.com) was used in a request to the Test environment (test.stytch.com). Try sending the request to live.stytch.com instead or using a different ID.
no_active_webauthn_registrations: No active WebAuthn registrations for this user ID and domain. To create one, first hit the WebAuthn register/start endpoint. Complete the registration by subsequently hitting the WebAuthn register endpoint.
no_invite_redirect_url: There are no invite redirect URLs registered. To set invite redirect URLs for this project please visit here. For more information on why this validation is necessary please read more here.
no_invite_redirect_urls_set: Unable to verify the provided invite_magic_link_url. There are no invite redirect URLs set for this project so we are unable to verify the invite_magic_link_url provided in the request. To set invite redirect URLs for the project please visit the dashboard here. For more information on why this validation is necessary please read more here.
no_login_redirect_url: There are no login redirect URLs registered. To set login redirect URLs for this project please visit here. For more information on why this validation is necessary please read more here.
no_login_redirect_urls_set: Unable to verify the provided login_magic_link_url. There are no login redirect URLs set for this project so we are unable to verify the login_magic_link_url provided in the request. To set login redirect URLs for the project please visit the dashboard here. For more information on why this validation is necessary please read more here.
no_match_for_provided_magic_link_url: The magic_link_url in the request did not match any redirect URLs set for the project. Please visit the Stytch dashboard here to update the redirect URLs for the project. For more information on why this validation is necessary please read more here.
no_pending_webauthn_registration: Unable to find a pending registration tied to this user. Please ensure you've first hit the WebAuthn register/start endpoint with the supplied user ID.
no_session_revoke_arguments: Please include a session_id, session_token, or session_jwt. Exactly one of those values is required to revoke a session.
no_signup_redirect_url: There are no sign-up redirect URLs registered. To set sign-up redirect URLs for this project please visit here. For more information on why this validation is necessary please read more here.
no_signup_redirect_urls_set: Unable to verify the provided signup_magic_link_url. There are no sign-up redirect URLs set for this project so we are unable to verify the signup_magic_link_url provided in the request. To set signup redirect URLs for the project please visit the dashboard here. For more information on why this validation is necessary please read more here.
oauth_invalid_state: The OAuth state is invalid. Please reach out to the application developer for support.
oauth_state_mismatch: The state in the cookie doesn't match with the state in the query parameter. Please reach out to the application developer for support.
oauth_token_not_found: The OAuth token provided can not be found. This may be because the token never existed, or has already been used successfully.
private_key_too_long: Private key is too long. Please make sure you have the correct value.
pending_totp_exists: Cannot create a new TOTP for the specified user since the user has a pending TOTP that has not yet expired. Please try creating a new TOTP for the user once the pending one has expired or delete the pending TOTP before attempting to create a new one.
query_params_do_not_match: The magic_link_url in the request provided query parameters that did not match any redirect URLs set on the Stytch dashboard for the project. Please visit the Stytch dashboard here to make any necessary updates. For more information on why this validation is necessary please read more here.
recovery_code_used_as_totp_code: The totp_code submitted was invalid. Based on the format of the submitted value it looks like a recovery_code was entered instead. To authenticate a recovery_code please use the /v1/totps/recover endpoint. You can read more here: https://stytch.com/docs/api/totp-recover.
test_id_used_in_live_environment: Invalid argument sent to Live environment. An ID associated with the Test environment (test.stytch.com) was used in a request to the Live environment (api.stytch.com). Try sending the request to test.stytch.com instead or using a different ID.
too_many_session_revoke_arguments: Please ensure only one of the following is passed: session_id, session_token, or session_jwt. Exactly one of those values is required to revoke a session.
too_many_session_arguments: Please include at most one of session_token or session_jwt in an authenticate request, not both.
totp_code_used_as_recovery_code: The recovery_code submitted was invalid. Based on the format of the submitted value it looks like a totp_code was entered instead. To authenticate a totp_code please use the /v1/totps/authenticate endpoint. You can read more here: https://stytch.com/docs/api/totp-authenticate.
unable_to_authenticate_crypto_wallet: The crypto wallet could not be authenticated.
unable_to_authorize_oauth_provider: Unable to authorize request to this OAuth provider. Please check your project's client ID and secret.
unable_to_parse_session_jwt: Unable to parse session JWT
unable_to_register_webauthn_registration: The WebAuthn registration could not be registered.
unsupported_characters: Unsupported characters were provided. Try again using allowed characters. Valid characters include all Unicode letters, numbers, and these symbols ' & - _ . ,
enterprise_endpoint: The endpoint you requested requires approval before using. Please reach out to support@stytch.com if you're interested.
unable_to_authenticate_recovery_code: Unable to authenticate recovery_code.
unable_to_authenticate_totp: Unable to authenticate totp_code.
unable_to_auth_magic_link: Unable to authenticate the magic link provided. Check that it hasn't expired, the token is valid, and any additional security configurations were satisfied
unable_to_auth_otp_code: Unable to authenticate the one-time passcode provided. Check that it hasn't expired, the code is valid, and any additional security configurations were satisfied
unable_to_auth_webauthn_registration: WebAuthn registration could not be authenticated.
unauthorized_credentials: The provided credentials (project_id and secret) were invalid. Check that the secret is an active one for the given project.
unauthorized_credentials_homepage: The credentials used were the credentials from the Stytch homepage. Please create an account and use the credentials provided for your project.
unauthorized_project_id_live: The provided credentials look like they were live credentials being used against the test API. Try using the test project_id and secret for your project.
unauthorized_project_id_test: The provided credentials look like they were test credentials being used against the live API. Try using the live project_id and secret for your project.
organization_suspended: The organization for the provided project has been suspended. Please contact support@stytch.com for assistance.
use_https: Please use https rather than http when hitting the Stytch API.
apple_oauth_config_not_found: The Apple OAuth config was not found.
crypto_wallet_not_found: The crypto wallet was not found.
email_not_found: There was no email found for the supplied email or email_id.
phone_number_not_found: There was no phone number found for the supplied phone number or phone_id.
magic_link_not_found: The magic link was not found.
otp_code_not_found: The one-time passcode was not found.
project_not_found: The project provided was not found.
route_not_found: The route provided is not supported.
session_not_found: The session could not be found. It could be revoked, expired, or nonexistent.
totp_not_found: This TOTP could not be found.
totps_not_found_for_user: Unable to authenticate totp_code since no active or pending TOTPs could be found for the user.
totp_recovery_codes_not_found: The TOTP recovery_codes could not be found.
user_not_found: There was no user found for the supplied user_id.
webauthn_registration_not_found: The WebAuthn registration could not be found.
method_not_allowed: The method used is not supported.
too_many_requests: Too many requests hit the API too quickly. We rate limit suspicious user activity per user, email, or phone number separately from global project rate limits. If you run into this error, we recommend an exponential backoff of your requests.
too_few_tokens_authenticated: Too many requests without sufficient percentage of tokens authenticated
internal_server_error: Oops, something went wrong on our side. We recommend trying again.