Password login, signup, and reset with the API

Stytch's Passwords product allows your Members (end users) to sign up for or log in to an Organization (tenant) within your application with an email address (used as the username) and a password.

In this guide, you'll use our API to build a B2B Passwords flow that will let your end users sign up for an Organization, log in your application, and reset their password.

In order to complete this guide, you'll need the following:

• A Stytch B2B project. If you don't have one already, in the Dashboard, click on your existing project name in top left corner of the Dashboard, click Create a new project, and then select B2B Authentication.
• The project Test environment's project_id, secret, and public_token from the API keys section.

As a security precaution, we require that you explicitly set URLs in the Redirect URLs section of the Dashboard. End users are always routed to the redirect URLs after clicking an EML.

By default, all new projects have redirect URLs set to http://localhost:3000/authenticate for the Test environment in the Dashboard.

If your project doesn't have a redirect URL or if you need a different URL, click + Create redirect URL and provide a URL and set the Type to All.

For more information on why this step is necessary, please check out the resource on URL validation.

If you don't have one, create a new Organization by calling our Create an Organization endpoint.

It requires, at minimum, an organization_name and an organization_slug.

These Organization settings allow end users to be provisioned as Members when signing up for an Organization through Passwords. You can read more about Organization settings here.

curl --request POST \
	--url https://test.stytch.com/v1/b2b/organizations \
	-u '{PROJECT_ID}:{SECRET}' \
	-H 'Content-Type: application/json' \
	-d '{
		"organization_name": "Example Org Inc.",
		"organization_slug": "example-org"
	}'

Copy the organization_slug from response. You'll need it for Step 3 .

The first part of the Passwords flow is to verify the user has access to the email address they are signing up with. We'll use our Email Magic Link product to do so; this helps prevent against simple typos from end users and domain squatting attacks from malicious actors.

When calling the Send Login Or Signup Email endpoint, in the body parameters, provide the organization_id from Step 2 and the email_address of the end user who is signing up.

The Send Login Or Signup Email endpoint will send a signup email template (as opposed to a login email template) if the provided email_address does not match any existing Member of the Organization.

The email_address must have a domain that complies with the email_allowed_domains list from Step 2.

curl --request POST \
	--url https://test.stytch.com/v1/b2b/magic_links/email/login_or_signup \
	-u '{PROJECT_ID}:{SECRET}' \
	-H 'Content-Type: application/json' \
	-d '{
		"organization_id": "{ORGANIZATION_ID}",
		"email_address": "{EMAIL_ADDRESS}"
	}'

After a successful API call:

• A signup email with the Magic Link will be sent to the email_address, prompting the end user to create an account and join the specified Organization.
• A Member object will be created with a pending status and returned in the response.

When the end user clicks the signup EML, they will be redirected to the sign-up redirect URL you entered into the Dashboard in Step 1. Your application should have a route and page that handles the redirect URL and its query parameters. The full signup redirect URL will look like this:

{REDIRECT_URL}?slug=example-org&stytch_token_type=magic_links_token&token=SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=

Call the Authenticate Magic Link endpoint with:

• The token query param's value.
• An optional session_duration_minutes length to create a Session. If left empty, the default length for session_duration_minutes will be set to 60.

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

After a successful API call:

• The end user will be authenticated into the Organization as a Member.
• The Member record will have a active status.
• A Member Session object session_token, and session_jwt will be returned in the response.

Now that we've verified the end user has access to the email address they are signing up with, we can prompt them to create a password for their account.

Call the Password reset by session endpoint with the session_token or session_jwt from Step 4, the password the Member wants to create, and the Member's organization_id.

curl --request POST \
	--url https://test.stytch.com/v1/b2b/passwords/session/reset \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	  "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
	  "password": "24k^&+sJwKN$30Tv"
	  "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q"
	}'

After a successful API call:

• The Member will have a password set.
• A Member Session object session_token, and session_jwt will be returned in the response.

When a Member with a password returns to your application, call the Passwords authenticate endpoint with the email_address, password, and organization_id of the Member to log them in.

curl --request POST \
	--url https://test.stytch.com/v1/b2b/passwords/authenticate \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	  "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
	  "email_address": "{EMAIL_ADDRESS}",
	  "password": "24k^&+sJwKN$30Tv",
	  "session_duration_minutes": 10080
	}'

After a successful API call:

• The Member will be authenticated into the Organization.
• A Member Session object, session_token, and session_jwt will be returned in the response.

When a Member forgets their password, you can prompt them to reset it by sending them a password reset email. This flow involves a two step process, sending the password reset email and then accepting the user's new password after they click the reset link in the email.

First call the Password reset by email start endpoint with the email_address of the Member to send them a password reset email.

curl --request POST \
	--url https://test.stytch.com/v1/b2b/passwords/email/reset/start \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	  "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
	  "email_address": "{EMAIL_ADDRESS}",
	  "reset_password_redirect_url": "https://someexample.com",
      "login_redirect_url": "https://someexample.com",
      "reset_password_expiration_minutes": 10
	}'

Once the user clicks the Reset password link in the email they'll be redirected to the reset_password_redirect_url that you specified above.

On that page prompt the user to input a new password and then call the Password reset by email endpoint with the token query param's value and the password the Member wants to create.

curl --request POST \
	--url https://test.stytch.com/v1/b2b/passwords/email/reset \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	  "password_reset_token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
	  "password": "24k^&+sJwKN$30Tv"
	}'

After a successful API call:

• The Member will have a new password set.
• The Member will be authenticated into the Organization.
• A Member Session object, session_token, and session_jwt will be returned in the response.

Build a user interface that allows end users to log in and sign up with EML. You'll also need to build a page to handle the redirect back to your application in Step 4 after an end user clicks on an EML.

Clone our B2B Next.js example app for helpful templates that can get you started quickly. Also check out our interactive B2B demo app to see the app in action.