Send a login or signup Email Magic Link

Stytch's Email Magic Link (EML) product allows your end users to sign up for or log in to an Organization within your application with a single click by sending a tokenized URL to their email inboxes.

In this guide, you'll learn how to use EML to sign up Members for a specific Organization. By the end, you'll have:

• Created an Organization.
• Sent a signup EML to an end user's email inbox.
• Provisioned the end user as a Member of the Organization.
• Sent a login EML to the Member's email inbox.
• Authenticated the Member.

Before you start

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 and secret from the API keys section. You'll need to pass these values into the Authorization request header for every Stytch API call.

Step 1: Add or update redirect URLs in the Dashboard

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 for ALL or individual URLs for Login and Sign-up.

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

Step 2: Create a new Organization

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

It requires, at minimum, an organization_name. For the purposes of this guide, you also need to set email_jit_provisioning to RESTRICTED and provide the email_allowed_domains list with an email domain your Members will sign up with (for example stytch.com or exampleorg.com).

These Organization settings allow end users to be provisioned as Members when signing up for an Organization through EML. 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",
        "email_allowed_domains": ["exampleorg.com"],
        "email_jit_provisioning": "RESTRICTED"
	}'

Copy the organization_id from response. You'll need it for the next step.

Step 3: Call the Send Login or Signup Email endpoint for signup

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

Step 4: Authenticate the signup EML token

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": 5
	}'

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.

Step 5: Call the Send Login Or Signup Email endpoint for login

To log the Member (and other already existing Members) back in to the Organization, call the same Send Login or Signup Email endpoint.

For already active Members of an Organization, the Send Login Or Signup Email endpoint will always send login email templates to that Member's registered email_address.

In the body parameters, provide the same organization_id and email_address from Step 3.

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

A login email with the Magic Link will be sent to the Member's email_address.

Step 6: Authenticate the login EML token

Just like in Step 4, the Member will be redirected to the login redirect URL from Step 1. Call the same Authenticate Magic Link endpoint with the new token from the query params and the desired session_duration_minutes.

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": "c7oNporEjCeBvAarynCC0nSSiYVDZJfiBgFl83zZASWV",
		"session_duration_minutes": 5
		"
	}'

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.

What's next

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.