Node

API reference

Explore the details of the Stytch API. Our authentication API is organized around REST principles and has resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.


Create user

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

Add a user to Stytch. A user_id is returned in the response that can then be used to perform other operations within Stytch. An email or a phone_number is required.


Body parameters


emailstring

The email to use for email magic links. This can be changed later via the update endpoint.


phone_numberstring

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.


nameobject

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

Collapse
first_namestring

The first name of the user.

middle_namestring

The middle name(s) of the user.

last_namestring

The last name of the user.


create_user_as_pendingboolean

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.


attributesobject

Provided attributes help with fraud detection.

Collapse
ip_addressstring

The IP address of the user.

user_agentstring

The user agent of the user.

REQUEST

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

RESPONSE

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

Get user

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

Fetch a given user to see what their various attributes are. All timestamps are formatted according to the ISO 8601 standard.


Path parameters


user_id*string

The user_id for the user to fetch.

REQUEST

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

RESPONSE

200
{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "name": {
    "first_name": "Jane",
    "middle_name": "",
    "last_name": "Doe"
  },
  "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
    }
  ],
  "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",
      "verified": true
    }
  ],
  "created_at": "2021-11-14T21:30:23Z",
  "status": "active"
}

Update user

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

Update a user's attributes. For example, you can add additional emails or change the user's name.


Path parameters


user_id*string

The user_id to update.


Body parameters


nameobject

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

Collapse
first_namestring

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

middle_namestring

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

last_namestring

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


emailsobject

Multiple emails can exist for one user. Add additional emails via this endpoint. To delete an email, use the delete user email endpoint.

Collapse
emailstring

An email for the user.


phone_numbersobject

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
phone_numberstring

A phone number for the user. The phone number should be in E.164 format.


attributesobject

Provided attributes help with fraud detection.

Collapse
ip_addressstring

The IP address of the user.

user_agentstring

The user agent of the user.

REQUEST

Node
curl --request PUT \
	--url https://test.stytch.com/v1/users/user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6 \
	-u 'PROJECT ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "name": {
          "first_name": "Jane",
          "last_name": "Doe"
        },
        "emails": [
          {
            "email": "test@stytch.com"
          }
        ]
	  }'

RESPONSE

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

Delete user

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

Remove a user from Stytch.


Path parameters


user_id*string

The user_id to be deleted.

REQUEST

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

RESPONSE

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

Delete user email

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

Remove an email from a given user.


Path parameters


email_id*string

The email_id to be deleted.

REQUEST

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

RESPONSE

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

Delete user phone number

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

Remove a phone number from a given user.


Path parameters


phone_id*string

The phone_id to be deleted.

REQUEST

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

RESPONSE

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

Beta

Delete user WebAuthn registration

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

Delete a previously created WebAuthn registration.


Path parameters


webauthn_registration_id*string

The webauthn_registration_id to be deleted.

REQUEST

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

RESPONSE

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

Get pending users

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

Fetch all users with a pending status. Users will show up here if they are added via the invite_by_email endpoint or via login_or_create where create_as_pending = true and have yet to create their account by clicking on the magic link in the email. All timestamps are formatted according to the ISO 8601 standard.


Query parameters


limitint

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


starting_after_idstring

The user ID to start after.

REQUEST

Node
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

200
{
  "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
        }
      ],
      "status": "pending",
      "created_at": "2020-12-18T07:41:52Z",
      "invited_at": "2020-12-18T07:41:52Z"
    }
  ],
  "has_more": false,
  "next_starting_after_id": "",
  "total": 1
}

Send magic link by email

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

Send a magic link to an existing Stytch user using their email address. If you'd like to create a user and send them a magic link by email with one request, use our log in or create endpoint.


Body parameters


email*string

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


login_magic_link_url*string

The URL that users click from the login email magic link. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's authenticate endpoint and finishes the login.


signup_magic_link_url*string

The url the user clicks from the sign up email magic link. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's authenticate endpoint and finishes the login.


login_expiration_minutesint

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


signup_expiration_minutesint

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


attributesobject

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

Collapse
ip_addressstring

The IP address of the user.

user_agentstring

The user agent of the user.

REQUEST

Node
curl --request POST \
	--url https://test.stytch.com/v1/magic_links/email/send \
	-u 'PROJECT ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "email": "test@stytch.com",
        "login_magic_link_url": "https://example.com/login",
        "signup_magic_link_url": "https://example.com/signup"
	}'

RESPONSE

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

Log in or create user by email

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

Send either a login or signup magic link to the user based on if the email is associated with a user already. A new or pending user will receive a signup magic link. An active user will receive a login magic link. For more information on how to control the status your users are created in see the create_user_as_pending flag.


Body parameters


email*string

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


login_magic_link_url*string

The url the user clicks from the login email magic link. This should be a url that your app receives and parses and subsequently send an api request to authenticate the magic link and log in the user.


signup_magic_link_url*string

The url the user clicks from the sign up email magic link. This should be a url that your app receives and parses and subsequently send an api request to authenticate the magic link and sign up the user.


login_expiration_minutesint

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


signup_expiration_minutesint

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


create_user_as_pendingboolean

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


attributesobject

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

Collapse
ip_addressstring

The IP address of the user.

user_agentstring

The user agent of the user.

REQUEST

Node
curl --request POST \
	--url https://test.stytch.com/v1/magic_links/email/login_or_create \
	-u 'PROJECT ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "email": "test@stytch.com",
        "login_magic_link_url": "https://example.com/login",
        "signup_magic_link_url": "https://example.com/signup"
	}'

RESPONSE

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

Invite by email

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

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


Body parameters


email*string

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


invite_magic_link_url*string

The url the user clicks from the email magic link. This should be a url that your app receives and parses and subsequently send an api request to authenticate the magic link and log in the user.


invite_expiration_minutesint

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


nameobject

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

Collapse
first_namestring

The first name of the user.

middle_namestring

The middle name(s) of the user.

last_namestring

The last name of the user.


attributesobject

Provided attributes help with fraud detection.

Collapse
ip_addressstring

The IP address of the user.

user_agentstring

The user agent of the user.

REQUEST

Node
curl --request POST \
	--url https://test.stytch.com/v1/magic_links/email/invite \
	-u 'PROJECT ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	    "email": "test@stytch.com",
        "invite_magic_link_url": "https://example.com"
	}'

RESPONSE

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

Revoke a pending invite

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

Revoke a pending invite based on the email provided.


Body parameters


email*string

The email of the user to revoke invite for.

REQUEST

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

RESPONSE

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




SMS one-time passcodes overview

SMS OTP sends a one-time passcode to the user's phone number. The user will then need to submit that code to login. This product currently supports US, Canadian, and South African phone numbers. Please reach out to let us know what countries you'd like us to support in the future. Send us a note at support@stytch.com.


Send one-time passcode by SMS

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

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.


Body parameters


phone_number*string

The US or Canadian phone number of the user to send a one-time passcode to. The phone number should be in E.164 format (i.e. +1XXXXXXXXXX).


expiration_minutesint

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.


attributesobject

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

Collapse
ip_addressstring

The IP address of the user.

user_agentstring

The user agent of the user.

REQUEST

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

RESPONSE

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

Log in or create user by SMS

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

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.


Body parameters


phone_number*string

The US or Canadian phone number of the user to send a one-time passcode. The phone number should be in E.164 format (i.e. +1XXXXXXXXXX).


expiration_minutesint

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.


create_user_as_pendingboolean

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.


attributesobject

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

Collapse
ip_addressstring

The IP address of the user.

user_agentstring

The user agent of the user.

REQUEST

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

RESPONSE

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

Send one-time passcode by WhatsApp

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

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.


Body parameters


phone_number*string

The phone number of the user to send a one-time passcode to. The phone number should be in E.164 format.


expiration_minutesint

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.


attributesobject

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

Collapse
ip_addressstring

The IP address of the user.

user_agentstring

The user agent of the user.

REQUEST

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

RESPONSE

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

Log in or create user by WhatsApp

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

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.


Body parameters


phone_number*string

The phone number of the user to send a one-time passcode. The phone number should be in E.164 format.


expiration_minutesint

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.


create_user_as_pendingboolean

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.


attributesobject

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

Collapse
ip_addressstring

The IP address of the user.

user_agentstring

The user agent of the user.

REQUEST

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

RESPONSE

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

Email one-time passcodes overview

Email OTP sends a one-time passcode to the user's email. The user will then need to submit that code to login. This product is currently in beta and customizing the email template is not yet supported. We'd love to hear any feedback you have. Send us a note at support@stytch.com.


Send one-time passcode by email

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

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.


Body parameters


email*string

The email of the user to send the one-time passcode to.


expiration_minutesint

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.


attributesobject

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

Collapse
ip_addressstring

The IP address of the user.

user_agentstring

The user agent of the user.

REQUEST

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

RESPONSE

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

Log in or create user by email OTP

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

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.


Body parameters


email*string

The email of the user to send the one-time passcode to.


expiration_minutesint

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.


create_user_as_pendingboolean

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.


attributesobject

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

Collapse
ip_addressstring

The IP address of the user.

user_agentstring

The user agent of the user.

REQUEST

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

RESPONSE

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

Authenticate one-time passcode

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

Authenticate a user given a method ID and a code. This endpoint verifies that the code is valid, hasn't expired, and any optional security settings such as IP match or user agent match are satisfied.


Body parameters


method_id*string

The ID of the method used to send a one-time passcode.


code*string

The code to authenticate.


optionsobject

Specify optional security settings

Collapse
ip_match_requiredboolean

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

user_agent_match_requiredboolean

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


attributesobject

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

Collapse
ip_addressstring

The IP address of the user.

user_agentstring

The user agent of the user.


session_duration_minutesint

(Beta) Set the session lifetime to be this many minutes from now. This will start a new session if one doesn't already exist.


session_tokenstring

(Beta) Reuse an existing session instead of creating a new one. If this session token is for a different user than the OTP code, the session token will be ignored.

REQUEST

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

RESPONSE

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

OAuth overview

OAuth is a popular authentication framework that delegates authentication to an external identity provider (often shortened to IdP) like Google, Facebook, Apple, and Microsoft. A user relies on their membership from that provider to sign in instead of creating another password, and developers can enrich their users' experiences with the information shared by the providers. While OAuth has many benefits, developers need to understand the OAuth framework well to implement it securely. Stytch's OAuth product simplifies the process by abstracting the implementation details of OAuth for developers. The steps for an OAuth flow are simple:

  • 1. Add the required client ID and client secret from the IdP to the Stytch developer dashboard.
  • 2. Embed the client side OAuth URL (i.e Google) for that IdP that the user will click.

  • 3. Add an endpoint in the backend that calls oauth-authenticate to finish the flow.


Start Google OAuth flow

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

A client-side endpoint (can only be queried from the user's browser) that starts the Google OAuth flow. This endpoint generates the Google OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Google Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_urlor signup_redirect_url URLs provided.


Query parameters


public_token*string

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


login_redirect_urlstring

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.


signup_redirect_urlstring

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.

REQUEST

Node
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

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

Beta

Start Microsoft OAuth flow

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

A client-side endpoint (can only be queried from the user's browser) that starts the Microsoft OAuth flow. This endpoint generates the Microsoft OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Microsoft Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_urlor signup_redirect_url provided.


Query parameters


public_token*string

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


login_redirect_urlstring

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.


signup_redirect_urlstring

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.

REQUEST

Node
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

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

Beta

Start Apple OAuth flow

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

A client-side endpoint (can only be queried from the user's browser) that starts the Apple OAuth flow. This endpoint generates the Apple OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Apple Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_urlor signup_redirect_url provided.


Query parameters


public_token*string

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


login_redirect_urlstring

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.


signup_redirect_urlstring

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.

REQUEST

Node
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

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

Authenticate OAuth token

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

Authenticate a user given a token. This endpoint verifies that the user completed the OAuth flow by verifying that the token is valid and hasn't expired. If the request is verified and a session is requested via the 'session_management_type' parameter, the response includes a session.


Body parameters


token*string

The token to authenticate.


session_management_typestring

Indicates what session management information should be returned. Valid options include 'none' for no session, 'stytch' for a Stytch session, and 'idp' for an identity provider (IdP session). An IdP session includes the JWT or access token returned by the provider.


session_duration_minutesint

(Beta) (Stytch sessions only) Set the lifetime of a Stytch session to be this many minutes from now. This will start a new session if one doesn't already exist. This argument can only be used for Stytch sessions, not for IdP sessions.


session_tokenstring

(Beta) (Stytch sessions only) Reuse an existing Stytch session instead of creating a new one. If this session token is for a different user than the magic token, the session token will be ignored. This argument can only be used for Stytch sessions, not for IdP sessions.

REQUEST

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

RESPONSE

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

Session management overview

Stytch user sessions are identified by a session token that should be stored client-side (usually a browser cookie) and authenticated on each request. To start a session, use the authenticate magic link or authenticate OTP endpoint as usual and add the session_duration_minutes parameter to set the lifetime of the session. Look for session_token in the response.


Beta

Get sessions

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

List all active sessions for a given user ID. All timestamps are formatted according to the ISO 8601 standard.


Query parameters


user_id*string

The user ID to get active sessions for.

REQUEST

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

RESPONSE

200
{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "sessions": [
    {
      "attributes": {
        "ip_address": "203.0.113.1",
        "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"
      },
      "authentication_factors": [
        {
          "delivery_method": "email",
          "email_factor": {
            "email_address": "sandbox@stytch.com",
            "email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
          },
          "last_authenticated_at": "2021-08-09T07:41:52Z",
          "type": "magic_link"
        }
      ],
      "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",
    }
  ],
}

Beta

Authenticate session

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

Authenticate a session token and retrieve associated session data. If session_duration_minutes is included, update the lifetime of the session to be that many minutes from now. All timestamps are formatted according to the ISO 8601 standard.


Body parameters


session_token*string

The session token to authenticate.


session_duration_minutesint

Set the session lifetime to be this many minutes from now.

REQUEST

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

RESPONSE

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

Beta

Revoke session

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

Revoke a session, immediately invalidating all of its session tokens. You can revoke a session in two ways: using its ID, or using one of its session tokens. This endpoint requires exactly one of those to be included in the request. It will return an error if both are present.


Body parameters


session_idstring

The session ID to revoke.


session_tokenstring

The session token to revoke.

REQUEST

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

RESPONSE

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

WebAuthn overview

The Web Authentication API (WebAuthn) is a specification that allows web applications on supported browsers to authenticate a user via authenticator types such as built-in device biometrics (e.g. facial recognition on mobile and fingerprint readers on desktop) or secure hardware keys (e.g. YubiKeys). While WebAuthn has many benefits, developers need to understand the API well to implement it securely. Stytch's WebAuthn product simplifies the process by abstracting the implementation details of WebAuthn for developers. The steps for a WebAuthn flow are:

  • 1. Begin the creation of a new WebAuthn registration by calling register start endpoint with an active user.

  • 2. Take the public_key_credential_creation_options from the response of the register start request and, from the browser, make a navigator.credentials.create() request with the public_key_credential_creation_options as 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.

  • 3. Complete the registration by calling the register endpoint with the response from the navigator.credentials.create() request 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.

  • 4. To authenticate a user using their authentication device, start by hitting the authenticate start endpoint.

  • 5. With the public_key_credential_request_options from the authenticate start response , make a navigator.credentials.get() request from the browser with the public_key_credential_request_optionsas the public key. Like in step 2, 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 of the fields to array buffers.

  • 6. Complete authentication by calling the authenticate endpoint with the response from the navigator.credentials.get() request as the public_key_credential parameter. 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.


Beta

Start register WebAuthn registration

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

Initiate the process of creating a new WebAuthn registration. After calling this endpoint, the browser will need to call navigator.credentials.create() with the data from public_key_credential_creation_options passed to the navigator.credentials.create() request via the public key argument. We recommend using the create()wrapper provided by the webauthn-json library. If you are not using the webauthn-json library, the public_key_credential_creation_optionswill need to be converted to a suitable public key by unmarshalling the JSON, base64 decoding the user ID field, and converting user ID and the challenge fields into an array buffer.


Body parameters


user_id*string

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


domain*string

The domain for the WebAuthn registration.


user_agentstring

The user_agent of the user.


authenticator_typestring

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

Node
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

200
{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  "public_key_credential_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"
    }
  }
}

Beta

Register WebAuthn registration

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

Complete the creation of a WebAuthn registration by passing the response from the navigator.credentials.create() request to this endpoint as the public_key_credential parameter. If the webauthn-json library's create() method was used, the response can be passed directly to the register endpoint. If not, some fields (the client data and the attestation object) from the navigator.credentials.create() response will need to be converted from array buffers to strings and marshalled into JSON.


Body parameters


user_id*string

The user_id the WebAuthn registration is tied to.


public_key_credential*json

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

REQUEST

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

RESPONSE

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

Beta

Start authenticate WebAuthn registration

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

Initiate the authentication of a WebAuthn registration. After calling this endpoint, the browser will need to call navigator.credentials.get() with the data from public_key_credential_request_options passed to the navigator.credentials.get() request via the public key argument. We recommend using the get()wrapper provided by the webauthn-json library. If you are not using the webauthn-json library, the public_key_credential_request_optionswill need to be converted to a suitable public key by unmarshalling the JSON and converting some the fields to array buffers.


Body parameters


user_id*string

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


domain*string

The domain for the WebAuthn authentication.

REQUEST

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

RESPONSE

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

Beta

Authenticate WebAuthn registration

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

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


Body parameters


public_key_credential*json

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


session_duration_minutesint

(Beta) Set the session lifetime to be this many minutes from now. This will start a new session if one doesn't already exist.


session_tokenstring

(Beta) Reuse an existing session instead of creating a new one. If this session token is for a different user than the WebAuthn registration, the session token will be ignored.

REQUEST

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

RESPONSE

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

Resources

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

Authentication

The Stytch API uses basic authentication for all API requests. The username will be your project_id and the password will be your secret. You can retrieve both your test and live API keys from the developer dashboard.

Environments

There are two environments, TEST and LIVE, each with unique API keys and urls, test.stytch.com and api.stytch.com. Additionally, the resources created in each environment are tied to the environment they were created in. The ids used for objects include the environment they are tried to, for example user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6.

Email templates

Email templates control the subject line and body of the email a user receives. For Magic Link endpoints that send emails, there are three possible email templates a user can receive: login, signup or invite. Which email template a user receives is based on a combination of the user's state in the Stytch backend and the endpoint used.

URL Validation

To ensure your users are always routed to the correct place, Stytch verifies any redirect URLs provided in requests against redirect URLs that are configured in the developer dashboard. For each redirect URL type (login, signup or invite), a developer can specify one or more URLs for each type. Each project also has separate redirect URLs for the test and live environments. When verifying the redirect URL from the request against the predefined URLs for the project, Stytch looks for an exact match, including any subdirectories and query parameters. Please visit the dashboard to set redirect URLs for your project.

User states

A user's state impacts how they are treated within Stytch, in particular which email template they are sent. Users within Stytch can be in three different states: pending, active, or deleted.

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

Errors

Stytch uses HTTP response status codes to indicate the success or failure of your API requests. For failures, Stytch returns an error using the appropriate status code. There are three categories for status codes:

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

4xx errors generally require some action to be taken to resolve them. Below is a list of possible error codes that can be returned, along with additional information about how to resolve them. These types of errors also include the url attribute with a direct link to the specific error code it corresponds to.


400 Bad request

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

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_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 (e.g., not properly formatted) or missing. Check that the email address is properly formatted and only includes allowed characters.

invalid_email_id: The email_id is invalid (e.g., not properly formatted) or missing. email-test-81bf03a8-86e1-4d95-bd44-bb3495224953 is an example email_id.

invalid_expiration: The expiration_minutes is invalid (e.g., not properly formatted) or missing. Make sure the value provided is between 5 and 10080 minutes.

invalid_expiration_otp: The expiration_minutes is invalid (e.g., 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 (e.g., not properly formatted) or missing.

invalid_ip_address: The ip_address is invalid (e.g., not properly formatted) or missing.

invalid_login_magic_link_url: The login_magic_link_url is invalid (e.g., not properly formatted) or missing.

invalid_magic_link_url: The magic_link_url is invalid (e.g., not properly formatted) or missing.

invalid_method_id: The method_id is invalid (e.g., 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 (e.g., 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: Phone number is an invalid US or Canadian number. We're currently expanding beyond US and Canada for SMS support. Please reach out to support@stytch.com to let us know what countries you'd like us to support in the future.

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_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 (e.g., not properly formatted).

invalid_session_token: The session_token format is invalid (e.g., 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_signup_magic_link_url: The signup_magic_link_url is invalid (e.g., not properly formatted) or missing.

invalid_token: The token is invalid (e.g., not properly formatted) or missing.

invalid_user_agent: The user_agent is invalid (e.g., not properly formatted) or missing.

invalid_user_id: The user_id is invalid (e.g., not properly formatted) or missing. user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6 is an example user_id.

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_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_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 either a session_id or a session_token. Exactly one of those values is required to revoke a session.

no_signup_redirect_urls_set: Unable to verify the provided signup_magic_link_url. There are no signup 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.

private_key_too_long: Private key is too long. Please make sure you have the correct value.

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.

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 or session_token. Exactly one of those values is required to revoke a session.

too_many_user_registrations_for_domain: The provided user_id has reached the maximum allowed WebAuthn registrations for the provided domain. The maximum is 25.

unable_to_authorize_oauth_provider: Unable to authorize request to this OAuth provider. Please check your project's client ID and secret.

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 ' & - _ . ,


401 Unauthorized

enterprise_endpoint: The endpoint you requested requires approval before using. Please reach out to support@stytch.com if you're interested.

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.


403 Forbidden

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.


404 Not found

apple_oauth_config_not_found: The Apple OAuth config 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.

user_not_found: There was no user found for the supplied user_id.

webauthn_registration_not_found: The WebAuthn registration could not be found.


405 Method not allowed

method_not_allowed: The method used is not supported.


429 Too many requests

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


500 Internal server error

internal_server_error: Oops, something went wrong on our side. We recommend trying again.