B2B API Reference

REQUEST

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

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "organization": {
	"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
	"organization_logo_url": "",
	"organization_name": "Example Org Inc.",
	"organization_slug": "example-org",
	"email_allowed_domains": [],
	"email_invites": "ALL_ALLOWED",
	"email_jit_provisioning": "NOT_ALLOWED",
	"sso_default_connection_id": null,
	"sso_jit_provisioning": "NOT_ALLOWED",
	"sso_jit_provisioning_allowed_connections": [],
	"sso_active_connections": [],
	"trusted_metadata": {}
  }
}

Get an Organization

GEThttps://test.stytch.com/v1/b2b/organizations/{organization_id}

Returns an Organization specified by organization_id.

Path parameters

organization_id* string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

Response fields

request_id string

status_code int

organization object

REQUEST

curl --request GET \
	--url https://test.stytch.com/v1/b2b/organizations/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931 \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "organization": {
	"email_allowed_domains": [],
	"email_invites": "ALL_ALLOWED",
	"email_jit_provisioning": "NOT_ALLOWED",
	"organization_id": "organization-test-staging-12345",
	"organization_logo_url": "",
	"organization_name": "Example Org Inc",
	"organization_slug": "exampleorg",
	"sso_default_connection_id": null,
	"sso_jit_provisioning": "NOT_ALLOWED",
	"sso_jit_provisioning_allowed_connections": [],
	"sso_active_connections": [],
	"trusted_metadata": {}
  }
}

Update an Organization

PUThttps://test.stytch.com/v1/b2b/organizations/{organization_id}

Updates an Organization specified by organization_id. An Organization must always have at least one auth setting set to either RESTRICTED or ALL_ALLOWED in order to provision new Members.

*See the Organization authentication settings resource to learn more about fields like email_jit_provisioning, email_invites, sso_jit_provisioning, etc., and their behaviors.

Path parameters

organization_id* string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

Body parameters

organization_name string

The name of the Organization.

organization_slug string

The unique URL slug of the Organization. A minimnum of two characters is required. The slug only accepts alphanumeric characters and the following reserved characters: - . _ ~.

organization_logo_url string

The image URL of the Organization logo.

trusted_metadata object

An arbitrary JSON object for storing application-specific data.

email_jit_provisioning string

The authentication setting that controls how a new Member can be provisioned by authenticating via Email Magic Link. The accepted values are:

RESTRICTED – only new Members with verified emails that comply with email_allowed_domains can be provisioned upon authentication via Email Magic Link.

NOT_ALLOWED – disable JIT provisioning via Email Magic Link.

email_invites string

The authentication setting that controls how a new Member can be invited to an organization by email. The accepted values are:

ALL_ALLOWED – any new Member can be invited to join via email.

RESTRICTED – only new Members with verified emails that comply with email_allowed_domains can be invited via email.

NOT_ALLOWED – disable email invites.

email_allowed_domains array[strings]

An array of email domains that allow invites or JIT provisioning for new Members. This list is enforced when either email_invites or email_jit_provisioning is set to RESTRICTED.

Common domains such as gmail.com are not allowed. See the common email domains resource for the full list.

sso_default_connection_id string

The default connection used for SSO when there are multiple active connections.

sso_jit_provisioning string

The authentication setting that controls the JIT provisioning of Members when authenticating via SSO. The accepted values are:

ALL_ALLOWED – new Members will be automatically provisioned upon successful authentication via any of the Organization's sso_active_connections.

RESTRICTED – only new Members with SSO logins that comply with sso_jit_provisioning_allowed_connections can be provisioned upon authentication.

NOT_ALLOWED – disable JIT provisioning via SSO.

sso_jit_provisioning_allowed_connections array[strings]

An array of connection_ids that reference SAML Connection objects. Only these connections will be allowed to JIT provision Members via SSO when sso_jit_provisioning is set to RESTRICTED.

Response fields

request_id string

status_code int

organization object

REQUEST

curl --request PUT \
	--url https://test.stytch.com/v1/b2b/organizations/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931 \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"organization_name": "Example Org Inc.",
		"email_jit_provisioning": "ALL_ALLOWED"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "organization": {
	"email_allowed_domains": [],
	"email_invites": "ALL_ALLOWED",
	"email_jit_provisioning": "ALL_ALLOWED",
	"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
	"organization_logo_url": "",
	"organization_name": "Example Org Inc.",
	"organization_slug": "example-org",
	"sso_default_connection_id": null,
	"sso_jit_provisioning": "ALL_ALLOWED",
	"sso_jit_provisioning_allowed_connections": [],
	"sso_active_connections": [],
	"trusted_metadata": {}
  }
}

Search for Organizations

POSThttps://test.stytch.com/v1/b2b/organizations/search

Search for Organizations. If you send a request with no body params, no filtering will be applied and the endpoint will return all Organizations. All fuzzy search filters require a minimum of three characters.

Body parameters

cursor string

The cursor field allows you to paginate through your results. Each result array is limited to 1000 results. If your query returns more than 1000 results, 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, repeat the search call with the next_cursor value set to the cursor field to retrieve the next page of results. Continue to make search calls until the next_cursor in the response is null.

limit int

The number of Organizations to return per page, the default is 100. A maximum of 1000 Organizations 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.

query object

The optional query object contains the operator, i.e. AND or OR, and the operands that will filter your Organizations. Only an operator is required. If you include no operands, no filtering will be applied. If you include no query object, it will return all Organizations with no filtering applied.

Collapse

operator string

The action to perform on the operands. The accepted value are:

AND – all the operand values provided must match.

OR – the operator will return any matches to at least one of the operand values you supply.

operands array[objects]

An array of operand objects that contains all of the filters and values to apply to your search search query.

Collapse

filter_name string

The type of search filter to apply. The accepted values are: organization_ids, organization_slugs, organization_name_fuzzy, organization_slug_fuzzy, member_emails, member_email_fuzzy, allowed_domains, allowed_domain_fuzzy.

filter_value string or array

The values to search for based on which filter_name is applied.

Collapse

organization_ids array[strings]

An array of organization_ids to search for by exact match, when filter_name = "organization_ids".

organization_slugs array[strings]

An array of organization_slugs to search for by exact match, when filter_name = "organization_slugs".

organization_slug_fuzzy string

The organization_slug to search for by fuzzy match, when filter_name = "organization_slug_fuzzy".

organization_name_fuzzy string

The organization_name to search for by fuzzy match, when filter_name = "organization_name_fuzzy".

member_emails array[strings]

An array of Member email_address's to search for by exact match, when filter_name = "member_emails".

member_email_fuzzy string

The Member's email_address to search for by fuzzy match, when filter_name = "member_email_fuzzy".

allowed_domains array[strings]

An array of email domains to search for by exact match, when filter_name = "allowed_domains".

allowed_domain_fuzzy string

The email domain to search for by fuzzy match, when filter_name = "allowed_domain_fuzzy".

results_metadata object

The search results_metadata object contains metadata relevant to your specific query like total and next_cursor.

Collapse

next_cursor string

The next_cursor string is returned when your search results contain more than one page of results. To retrieve the next page, set the next_cursor value to the cursor field and repeat the search query.

total int

The total number of results that match your query.

Response fields

request_id string

status_code int

organizations array[objects]

An array of Organization objects.

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/b2b/organizations/search \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"limit": 200,
		"query": {
			"operator": "OR",
			"operands": [
				{
					"filter_name": "allowed_domains",
					"filter_value": ["stytch.com"]
				},
				{
					"filter_name": "organization_name_fuzzy",
					"filter_value": "example org"
				}
			]
		}
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "results_metadata": {
		"next_cursor": null,
		"total": 5
	},
  "organizations": [
		...
  ]
}

Delete an Organization

DELETEhttps://test.stytch.com/v1/b2b/organizations/{organization_id}

Deletes an Organization specified by organization_id. All Members of the Organization will also be deleted.

Path parameters

organization_id* string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

Response fields

request_id string

status_code int

organization_id string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

REQUEST

curl --request DELETE \
	--url https://test.stytch.com/v1/b2b/rganizations/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931 \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931"
}

Member object

Fields

organization_id string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

member_id string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

email_address string

The email address of the Member.

status string

The status of the Member. The possible values are: pending, invited, active, or deleted.

name string

The name of the Member.

trusted_metadata object

An arbitrary JSON object for storing application-specific or identity-provider-specific data.

untrusted_metadata object

An arbitrary JSON object of application-specific data. These fields can be edited directly by the frontend SDK, and should not be used to store critical information. See the Metadata resource for complete field behavior details.

sso_registrations array[objects]

An array of registered SAML Connection objects the Member has authenticated with.

Collapse

connection_id string

Globally unique UUID that identifies a specific SSO connection_id for a Member.

registration_id string

The id that registers an SSO connection to a Member upon successful authentication.

external_id string

The id given by the identity provider.

sso_attributes object

An object for storing SSO attributes brought over from the identity provider.

OBJECT

{
	"member": {
    "email_address": "sandbox@stytch.com",
    "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
    "name": "Test Member",
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "status": "active",
    "trusted_metadata": {
      "role": "admin",
      "teams": ["tech", "support"]
    },
    "untrusted_metadata": {
      "job_title": "Business Analyst",
      "preferred_locales": ["en", "es"]
    },
    "sso_registrations": [
      {
        "connection_id": "saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
        "external_id": "sandbox@stytch.com",
        "registration_id": "saml-member-registration-test-9a6d293d-d8b3-42e8-abb4-220cc2060e93"
        "sso_attributes": {
          "email": ["sandbox@stytch.com"],
          "first_name": ["Test"],
          "last_name": ["Member"]
        }
      }
    ],
  }
}

Create a Member

POSThttps://test.stytch.com/v1/b2b/organizations/{organization_id}/members

Creates a Member. An organization_id and email_address are required.

Path parameters

organization_id* string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

Body parameters

email_address* string

The email address of the Member.

name string

The name of the Member.

trusted_metadata object

An arbitrary JSON object for storing application-specific or identity-provider-specific data.

untrusted_metadata object

create_member_as_pending boolean

Flag for whether or not to save a Member as pending or active in Stytch. It defaults to false. If true, new Members will be created with status pending in Stytch's backend. Their status will remain pending and they will continue to receive signup email templates for every Email Magic Link until that Member authenticates and becomes active. If false, new Members will be created with status active.

Response fields

status_code int

request_id string

member_id string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

member object

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/b2b/organizations/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931/members \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
		"email_address": "sandbox@stytch.com",
		"name": "Carla Philips",
		"trusted_metadata": {
			"role": "admin"
		},
		"untrusted_metadata": {
			"nickname": "Carly",
			"preferred_locales": ["en", "es"]
		}
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f"
  "member": {...}
}

Update a Member

PUThttps://test.stytch.com/v1/b2b/organizations/{organization_id}/members/{member_id}

Updates a Member specified by organization_id and member_id.

Path parameters

organization_id* string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

member_id* string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

Body parameters

name string

The name of the Member.

trusted_metadata object

An arbitrary JSON object for storing application-specific or identity-provider-specific data.

untrusted_metadata object

Response fields

status_code int

request_id string

member_id string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

member object

REQUEST

curl --request PUT \
	--url https://test.stytch.com/v1/b2b/organizations/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931/members/member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
		"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
		"name": "Carla Philips",
		"trusted_metadata": {
			"role": "reader"
		},
		"untrusted_metadata": {
			"nickname": "Carli",
			"preferred_locales": ["en", "pt-br"]
		}
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f"
  "member": {...}
}

Search for Members

POSThttps://test.stytch.com/v1/b2b/organizations/members/search

Search for Members within specified Organizations. An array with at least one organization_id is required. Submitting an empty query returns all Members within the specified Organizations.

*All fuzzy search filters require a minimum of three characters.

Body parameters

organization_ids* array[string]

An array of organization_ids. At least one value is required.

cursor string

limit int

The number of Members to return per page, the default is 100. A maximum of 1000 members 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.

query object

The optional query object contains the operator, i.e. AND or OR, and the operands that will filter your Members. Only an operator is required. If you include no operands, no filtering will be applied. If you include no query object, it will return all Members with no filtering applied.

Collapse

operator string

The action to perform on the operands. The accepted values are:

AND – all the operand values provided must match.

OR – the operator will return any matches to at least one of the operand values you supply.

operands array[objects]

An array of operand objects that contain all of the filters and values to apply to your search search query.

Collapse

filter_name string

The type of search filter to apply. The accepted values are: member_ids, member_emails, member_email_fuzzy, statuses

filter_value string or array

The values to search for based on which filter_name is applied.

Collapse

member_ids array[strings]

An array of member_ids to search for by exact match, when filter_name = "member_ids".

member_emails array[strings]

An array of Member email_addresss to search for by exact match, when filter_name = "member_emails".

member_email_fuzzy string

The Member's email_address to search for by fuzzy match, when filter_name = "member_email_fuzzy".

statuses array[strings]

An array of Member's statuses to search for by exact match, when filter_name = "statuses". Deleted Members will not be returned.

results_metadata object

The Member search results_metadata object contains metadata relevant to your specific query like total and next_cursor.

Collapse

next_cursor string

total int

The total number of results that match your query.

Response fields

request_id string

status_code int

members array[objects]

An array of Member objects.

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/b2b/organizations/members/search \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"organization_ids": ["organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931"],
		"limit": 200,
		"query": {
			"operator": "OR",
			"operands": [
				{
					"filter_name": "member_emails",
					"filter_value": ["testmember@stytch.com"]
				},
				{
					"filter_name": "status",
					"filter_value": "active"
				}
			]
		}
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "results_metadata": {
		"next_cursor": null,
		"total": 5
	},
  "members": [
		...
  ]
}

Delete a Member

DELETEhttps://test.stytch.com/v1/b2b/organizations/{organization_id}/members/{member_id}

Deletes a Member specified by organization_id and member_id.

Path parameters

organization_id* string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

member_id* string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

Response fields

request_id string

status_code int

member_id string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

REQUEST

curl --request DELETE \
	--url https://test.stytch.com/v1/b2b/organizations/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931/members/member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f"
}

Send login or signup email

POSThttps://test.stytch.com/v1/b2b/magic_links/email/login_or_signup

Send either a login or signup magic link to a Member. A new, pending, or invited Member will receive a signup Email Magic Link. Members will have a pending status until they successfully authenticate. An active Member will receive a login Email Magic Link.

Body parameters

organization_id* string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

email_address* string

The email address of the Member.

login_redirect_url string

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

signup_redirect_url string

The URL the Member clicks from the signup 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.

pkce_code_challenge string

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

login_template_id string

Use a custom template for login emails. By default, it will use your default email template. The template must be from Stytch's built-in customizations or a custom HTML email for Magic Links - Login.

signup_template_id string

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

Response fields

request_id string

status_code int

member_id string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

member_created boolean

A flag indicating true if a new Member object was created and false if the Member object already existed.

member object

organization object

REQUEST

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-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
		"email_address": "sandbox@stytch.com"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
  "member_created": true,
  "member": {...},
  "organization": {...}
}

Send invite email

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

Send an invite email to a new Member to join an Organization. The Member will be created with an invited status until they successfully authenticate. Sending invites to pending Members will update their status to invited. Sending invites to already active Members will return an error.

Body parameters

organization_id* string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

email_address* string

The email address of the Member.

invite_redirect_url string

The URL that the Member clicks from the invite 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 invite flow. If this value is not passed, the default invite_redirect_url that you set in your Dashboard is used. If you have not set a default invite_redirect_url, an error is returned.

invite_template_id string

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

invited_by_member_id string

The member_id of the Member who sends the invite.

name string

The name of the Member.

trusted_metadata object

An arbitrary JSON object for storing application-specific or identity-provider-specific data.

untrusted_metadata object

Response fields

request_id string

status_code int

member_id string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

member object

organization object

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/b2b/magic_links/email/invite \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
		"email_address": "sandbox@stytch.com"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f"
  "member": {...},
  "organization": {...}
}

Authenticate Magic Link

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

Authenticate a Member with a Magic Link. This endpoint requires a Magic Link token that is not expired or previously used. Provide a value for session_duration_minutes to receive a Session. If the Member’s status is pending or invited, they will be updated to active.

Body parameters

magic_links_token* string

The Email Magic Link token to authenticate.

session_token string

Reuse an existing session instead of creating a new one. If you provide a session_token, Stytch will update the session. If the session_token and magic_links_token belong to different Members, the session_token will be ignored. This endpoint will error if both session_token and session_jwt are provided.

session_jwt string

Reuse an existing session instead of creating a new one. If you provide a session_jwt, Stytch will update the session. If the session_jwt and magic_links_token belong to different Members, the session_jwt will be ignored. This endpoint will error if both session_token and session_jwt are provided.

session_duration_minutes int

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

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

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

pkce_code_verifier string

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

session_custom_claims object

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

Response fields

request_id string

status_code int

member_id string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

method_id string

The email or device involved in the authentication.

member_session object

reset_sessions boolean

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

session_token string

A secret token for a given Stytch Session.

session_jwt string

The JSON Web Token (JWT) for a given Stytch Session.

organization_id string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

member object

organization object

REQUEST

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

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "method_id": "member-email-test-1dd089b3-8904-47ef-b943-987968e549d4",
  "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
  "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
  "reset_sessions": false,
  "session_jwt": "example_jwt",
  "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
  "member_session": {...},
  "member": {...},
  "organization": {...}
}

Send Discovery Email (coming soon)

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

Send a discovery magic link to an email address.

Body parameters

email_address* string

The email address to send the discovery Magic Link to.

discovery_redirect_url string

The URL that the end user clicks from the discovery Magic Link. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's discovery authenticate endpoint and continues the flow. If this value is not passed, the default discovery redirect URL that you set in your Dashboard is used. If you have not set a default discovery redirect URL, an error is returned.

pkce_code_challenge string

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

login_template_id string

Use a custom template for discovery emails. By default, it will use your default email template. The template must be from Stytch's built-in customizations or a custom HTML email for Magic Links - Login.

Response fields

status_code int

request_id string

REQUEST

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

RESPONSE

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

Authenticate Discovery Email (coming soon)

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

Authenticates the discovery Magic Link token and exchanges it for an Intermediate Session Token.

Path parameters

intermediate_magic_links_token* string

The Intermediate Email Magic Link token to authenticate.

pkce_code_verifier string

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

Response fields

status_code int

request_id string

intermediate_session_token string

The Intermediate Session Token. This token does not belong to a specific instance of a member, but may be exchanged for an existing Member Session or used to create a new organization.

email_address string

The email address.

discovered_organization array

An array of discovered_organization objects tied to the intermediate_session_token. See the Discovered Organization Object for complete details.

REQUEST

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

RESPONSE

{
	"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
	"status_code": 200,
	"intermediate_session_token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
	"email_address": "sandbox@stytch.com",
	"discovered_organizations": [{...}, {...}]
}

Session Management overview

Stytch Member Sessions are identified by a session_token or session_jwt that should be stored client-side (usually a browser cookie) and authenticated on each request. To start a session, call one of the authenticate endpoints (e.g. Email Magic Links or SSO) and add the session_duration_minutes parameter to set the lifetime of the session. Look for session_token and session_jwt in the response.

Session object

Fields

member_session_id string

Globally unique UUID that identifies a specific Session in the Stytch API. The member_session_id is critical to perform operations on an Session, so be sure to preserve this value.

member_id string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

started_at timestamp

The timestamp when the Session started.

last_accessed_at timestamp

The timestamp when the Session was last accessed.

expires_at timestamp

The timestamp when the Session will expire.

authentication_factors array[objects]

An array of different authentication factors that have initiated a Session.

custom_claims object

A custom claims map for the Session being authenticated. Claims will be included on the Session object and in the JWT. iss, sub, aud, exp, nbf, iat, jti are reserved claims. Total custom claims size cannot exceed four kilobytes.

OBJECT

{
  "member_session": {
    "member_session_id": "session-test-fe6c042b-6286-479f-8a4f-b046a6c46509",
    "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
    "started_at": "2023-01-09T07:41:52Z",
    "last_accessed_at": "2023-01-09T07:41:52Z",
    "expires_at": "2021-08-10T07:41:52Z",
    "authentication_factors": [
      {
        "delivery_method": "email",
        "email_factor": {
          "email_address": "sandbox@stytch.com",
          "email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
        },
        "last_authenticated_at": "2023-01-09T07:41:52Z",
        "type": "magic_link"
      }
    ],
    "custom_claims": {
      "claim1": "value1",
      "claim2": "value2",
    },
  }
}

Get Session

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

Retrieves all active Sessions for a Member.

Query parameters

organization_id* string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

member_id* string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

Response fields

request_id string

status_code int

member_sessions array[object]

An array of Session objects.

REQUEST

curl --request GET \
	--url https://test.stytch.com/v1/b2b/sessions?organization_id=organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931&member_id=member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \

RESPONSE

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

Authenticate Session

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

Authenticates a Session and updates its lifetime by the specified session_duration_minutes. If the session_duration_minutes is not specified, a Session will not be extended. This endpoint requires either a session_jwt or session_token be included in the request. It will return an error if both are present.

You may provide a JWT that needs to be refreshed and is expired according to its exp claim. A new JWT will be returned if both the signature and the underlying Session are still valid.

Body parameters

session_token string

A secret token for a given Stytch Session. Read more about session_token in our Session Management guide.

session_jwt string

The JSON Web Token (JWT) for a given Stytch Session. Read more about session_jwt in our Session Management guide.

session_duration_minutes int

The Session lifetime of 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.

session_custom_claims object

Response fields

request_id string

status_code int

member_session object

session_token string

A secret token for a given Stytch Session. Read more about session_token in our Session Management guide.

session_jwt string

The JSON Web Token (JWT) for a given Stytch Session. Read more about session_jwt in our Session Management guide.

member object

organization object

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/b2b/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",
	"member_session": {...},
	"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
	"session_jwt": "",
	"member": {...},
	"organization": {...}
}

Exchange Session (coming soon)

POSThttps://test.stytch.com/v1/b2b/session/exchange

Use this endpoint to exchange a Member's existing session for another session in a different Organization. This can be used to accept an invite, but not to create a new member via domain matching.

To create a new member via domain matching, use the Exchange Intermediate Session flow instead.

Body parameters

organization_id string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

session_token string

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

session_jwt string

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

Response fields

status_code int

request_id string

member_id string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

session_token string

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

session_jwt string

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

member_session object

member object

organization object

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/b2b/session/exchange \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"organization_id": "${organization_id}",
		"session_token": "${session_token}"
	}'

RESPONSE

{
	"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
	"status_code": 200,
	"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
	"session_jwt": "example_jwt",
	"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
	"member_session": {...},
	"member": {...},
	"organization": {...}
}

Revoke Session

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

Revoke a Session and immediately invalidate all its tokens. To revoke a specific Session, pass either the member_session_id, session_token, or session_jwt. To revoke all Sessions for a Member, pass the member_id.

Body parameters

member_session_id string

Globally unique UUID that identifies a specific Session in the Stytch API. The member_session_id is critical to perform operations on an Session, so be sure to preserve this value.

session_token string

A secret token for a given Stytch Session.

session_jwt string

The JSON Web Token (JWT) for a given Stytch Session.

member_id string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

Response fields

status_code int

request_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/b2b/sessions/revoke \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f"
	}'

RESPONSE

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

SSO Overview

Stytch allows your organizations to set up login flows with SAML, with OIDC coming soon. Read our SAML Guide for more info.

SAML Connection object

Fields

organization_id string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

connection_id string

Globally unique UUID that identifies a specific SAML Connection.

display_name string

A human-readable display name for the connection.

acs_url string

The URL of the Assertion Consumer Service. This value will be passed to the IdP to redirect the Member back to Stytch after a sign-in attempt. Read our SAML Overview for more info.

audience_uri string

The URL of the Audience Restriction. This value will indicate that Stytch is the intended audience of an assertion. Read our SAML Overview for more info.

attribute_mapping object

An object that represents the attributes used to identify a Member. This object will map the IdP-defined User attributes to Stytch-specific values. Required attributes: email and one of full_name or first_name and last_name.

idp_entity_id string

A globally unique name for the IdP. This will be provided by the IdP.

idp_sso_url string

The URL for which assertions for login requests will be sent. This will be provided by the IdP.

signing_certificates array

A list of X.509 certificates Stytch will use to sign its assertion requests. Certificates should be uploaded to the IdP.

Expand

verification_certificates array

A list of X.509 certificates Stytch will use to validate an assertion callback. Certificates should be populated from the IdP.

Expand

status string

The status of the connection. The possible values are pending or active. See the Update SAML Connection endpoint for more details.

OBJECT

{
  "connection": {
		"acs_url": "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"attribute_mapping": {
			"email": "email",
			"full_name": "name"
		},
		"audience_uri":  "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"connection_id": "saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"display_name": "Example SAML Connection",
		"idp_entity_id": "https://idp.example.com/51861cbc-d3b9-428b-9761-227f5fb12be9",
		"idp_sso_url": "https://idp.example.com/51861cbc-d3b9-428b-9761-227f5fb12be9/sso/saml",
		"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
		"signing_certificates": [
			{
				"certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE",
				"created_at": "2023-01-01T00:00:00Z",
				"expires_at": "2033-01-01T00:00:00Z",
				"id": "",
				"issuer": "Stytch"
			}
		],
		"status": "active",
		"verification_certificates": [
			{
				"certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE",
				"created_at": "2023-01-01T00:00:00Z",
				"expires_at": "2033-01-01T00:00:00Z",
				"id": "saml-verification-key-test-5ccbc642-9373-42b8-928f-c1646c868701",
				"issuer": ""
			}
		]
	},
}

Create SAML Connection

POSThttps://test.stytch.com/v1/b2b/sso/saml/{organization_id}

Create a new SAML Connection.

Path parameters

organization_id string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

Body parameters

display_name string

A human-readable display name for the connection.

Response fields

status_code int

request_id string

connection object

The SAML Connection object affected by this API call. See the SAML Connection Object for complete response field details.

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/b2b/sso/saml/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931 \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	  "display_name": "Example SAML Connection"
	}'

RESPONSE

{
	"connection": {
		"acs_url":  "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"attribute_mapping": {
			"email": "email",
			"full_name": "name",
		},
		"audience_uri":  "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"connection_id": "saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"display_name": "",
		"idp": "",
		"idp_entity_id": "",
		"idp_sso_url": "",
		"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
		"signing_certificates": [
			{
				"certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE",
				"id": "",
				"created_at": "2023-01-01T00:00:00Z",
				"expires_at": "2033-01-01T00:00:00Z",
				"issuer": "Stytch"
			}
		],
		"status": "pending",
		"verification_certificates": []
	},
	"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
	"status_code": 200
}

Update SAML connection

PUThttps://test.stytch.com/v1/b2b/sso/saml/{organization_id}/connections/{connection_id}

Updates an existing SAML connection.

Note that a newly created connection will not become active until all of the following are provided:

idp_sso_url
attribute_mapping
idp_entity_id
x509_certificate

Path parameters

organization_id string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

connection_id string

Globally unique UUID that identifies a specific SAML Connection.

Body parameters

idp_entity_id string

The entity ID of the IdP. This is usually a URL that is provided by your IdP.

display_name string

A human-readable name to identify your SAML connection.

attribute_mapping object

Collapse

email* string

The key that will be sent by the IdP to indicate the member's email. If your IdP is configured to have email as its Name ID format, you may use nameID for the value here.

full_name string

The key that will be sent by the IdP to indicate the member's full name.

idp_sso_url* string

The URL that Stytch will direct its authentication requests to. This is usually a URL that is provided by your IdP.

x509_certificate* string

A certificate that Stytch will use to verify the sign-in assertion sent by the IdP, in PEM format. See our X509 guide for more info.

Response fields

status_code int

request_id string

connection object

The SAML Connection object.

Expand

REQUEST

curl --request PUT \
	--url https://test.stytch.com/v1/b2b/sso/saml/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931/connections/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9 \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"entity_id": "https://idp.example.com/51861cbc-d3b9-428b-9761-227f5fb12be9",
		"display_name": "Example SAML Connection",
		"attribute_mapping": {
		  "email": "NameID",
		  "first_name": "firstName",
		  "last_name": "lastName"
		},
		"idp_sso_url": "https://idp.example.com/51861cbc-d3b9-428b-9761-227f5fb12be9/sso/saml",
		"x509_certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE"
	}'

RESPONSE

{
  "connection": {
		"acs_url": "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"attribute_mapping": {
			"email": "email",
			"full_name": "name"
		},
		"audience_uri":  "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"connection_id": "saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"display_name": "Example SAML Connection",
		"idp_entity_id": "https://idp.example.com/51861cbc-d3b9-428b-9761-227f5fb12be9",
		"idp_sso_url": "https://idp.example.com/51861cbc-d3b9-428b-9761-227f5fb12be9/sso/saml",
		"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
		"signing_certificates": [
			{
				"certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE",
				"created_at": "2023-01-01T00:00:00Z",
				"expires_at": "2033-01-01T00:00:00Z",
				"id": "",
				"issuer": "Stytch"
			}
		],
		"status": "active",
		"verification_certificates": [
			{
				"certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE",
				"created_at": "2023-01-01T00:00:00Z",
				"expires_at": "2033-01-01T00:00:00Z",
				"id": "saml-verification-key-test-5ccbc642-9373-42b8-928f-c1646c868701",
				"issuer": ""
			}
		]
	},
	"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
	"status_code": 200
}

Get SSO Connections

GEThttps://test.stytch.com/v1/b2b/sso/{organization_id}

Get all SSO Connections owned by the organization.

Path parameters

organization_id string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

Response fields

status_code int

request_id string

saml_connections array[Object]

The list of SAML Connections returned.

REQUEST

curl --request GET \
	--url https://test.stytch.com/v1/b2b/sso/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931 \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json'

RESPONSE

{
  "saml_connections": [{
		"acs_url": "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"attribute_mapping": {
			"email": "email",
			"full_name": "name"
		},
		"audience_uri":  "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"connection_id": "saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"display_name": "Example SAML Connection",
		"idp_entity_id": "https://idp.example.com/51861cbc-d3b9-428b-9761-227f5fb12be9",
		"idp_sso_url": "https://idp.example.com/51861cbc-d3b9-428b-9761-227f5fb12be9/sso/saml",
		"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
		"signing_certificates": [
			{
				"certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE",
				"created_at": "2023-01-01T00:00:00Z",
				"expires_at": "2033-01-01T00:00:00Z",
				"certificate_id": "${signingCertificateId}",
				"issuer": "Stytch"
			}
		],
		"status": "active",
		"verification_certificates": [
			{
				"certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE",
				"created_at": "2023-01-01T00:00:00Z",
				"expires_at": "2033-01-01T00:00:00Z",
				"certificate_id": "saml-verification-key-test-5ccbc642-9373-42b8-928f-c1646c868701",
				"issuer": "CN=Google,OU=Google For Work,O=Google Inc.,L=Mountain View,ST=California,C=US"
			}
		]
	}],
	"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
	"status_code": 200
}

Delete SSO Connection

DELETEhttps://test.stytch.com/v1/b2b/sso/{organization_id}/connections/{connection_id}

Delete an existing SSO connection.

Query parameters

organization_id* string

The organization ID that the SAML connection belongs to.

connection_id* string

The ID of the SAML connection.

Response fields

status_code int

request_id string

connection_id string

The connection_id that was deleted as part of the delete request.

REQUEST

curl --request DELETE \
	--url https://test.stytch.com/v1/b2b/sso/{organization_id}/connections/{connection_id} \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json'

RESPONSE

{
  "connection_id": "saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "status_code": 200
}

Start SSO Login Flow

GEThttps://test.stytch.com/v1/public/sso/start?connection_id={connection_id}&public_token={public_token}

A client-side endpoint (can only be queried from the user's browser) that starts the SSO Authentication flow. This endpoint redirects the User to the IdP with all of the information required to complete the SSO Authentication flow. From there, the user signs into their IdP before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the redirect_url configured in the dashboard.

Query parameters

connection_id* string

The ID of the SSO connection to use for the login flow.

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.

pkce_code_challenge string

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

login_redirect_url string

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

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

signup_redirect_url string

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

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

Response fields

status_code int

request_id string

redirect_url string

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

REQUEST

curl --url https://test.stytch.com/v1/public/sso/start?connection_id=saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9&public_token=PUBLIC_TOKEN

RESPONSE

{
  "status_code": 302,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "redirect_url": "https://idp.example.com/51861cbc-d3b9-428b-9761-227f5fb12be9/sso/saml"
}

Authenticate SSO Login

POSThttps://test.stytch.com/v1/b2b/sso/authenticate

Authenticate a user given a token. This endpoint verifies that the user completed the SSO Authentication flow by verifying that the token is valid and hasn't expired. To initiate a Stytch session for the user while authenticating their SSO token, include the session_duration_minutes param. To link this authentication event to an existing Stytch session, include either the session_token or session_jwt param.

Body parameters

sso_token* string

The token to authenticate.

session_custom_claims map<string, any>

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

session_duration_minutes int

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

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

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

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

session_jwt string

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

session_token string

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

pkce_code_verifier string

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

Response fields

status_code int

request_id string

member_id string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

organization_id string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

member object

organization object

session_token string

A secret token for a given Stytch Session.

session_jwt string

The JSON Web Token (JWT) for a given Stytch Session.

member_session object

reset_sessions boolean

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/b2b/sso/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",
  "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
  "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
  "member": {...},
  "organization": {...},
  "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
  "session_jwt": "eyJ...",
  "member_session": {...},
}

Delete Verification Certificate

DELETEhttps://test.stytch.com/v1/b2b/sso/saml/{organization_id}/connections/{connection_id}/verification_certificates/{certificate_id}

Delete a SAML verification certificate.

You may need to do this when rotating certificates from your IdP, since Stytch allows a maximum of 5 certificates per connection. There must always be at least one certificate per active connection.

Path parameters

organization_id* string

The organization ID that the SAML connection belongs to.

connection_id* string

The ID of the SAML connection.

certificate_id* string

The ID of the certificate to be deleted.

Response fields

status_code int

request_id string

certificate_id string

The ID of the certificate that was deleted.

REQUEST

curl --request DELETE \
	--url https://test.stytch.com/v1/b2b/sso/saml/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931/connections/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9/verification_certificates/saml-verification-key-test-5ccbc642-9373-42b8-928f-c1646c868701 \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "certificate_id": "saml-verification-key-test-5ccbc642-9373-42b8-928f-c1646c868701",
}

Discovery Overview

The Discovery product lets Members discover and log in to Organizations they are a Member of, invited to, or eligible to join.

Unlike our other B2B products, Discovery allows end users to authenticate without specifying an Organization. Once an end user authenticates, an Intermediate Session is returned along with a list of associated Organizations.

A Member can then authenticate to the desired Organization by passing the Intermediate Session and organization_id. End users can even create a new Organization instead of joining or logging in to an existing one.

Members can also use Discovery to switch between Organizations by supplying a Session to exchange.

Discovered Organization object

Fields

organization object

membership object

Information about the membership

Collapse

kind string

Either active_member pending_member, invited_member, or eligible_to_join_by_email_domain

member object

The Member object if one already exists, or null if one does not.

details object

An object containing additional metadata about the membership, if available.

OBJECT

{
  "organization": {
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "organization_name": "Example Org Inc.",
    "organization_slug": "example-org",
    ...
  },
  "membership": {
    "kind": "active_member",
    "member": {
      "email_address": "sandbox@stytch.com",
      "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
      "name": "Test Member",
      "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
      "status": "active",
      ...
    },
    "details": null
  }
}

List Discovered Organizations

POSThttps://test.stytch.com/v1/b2b/discovery/organizations

List all possible organization relationships connected to a Member Session or Intermediate Session.

When a Member Session is passed in, relationships with a type of active_member, pending_member, or invited_member will be returned, and any membership can be assumed by calling the Exchange Session endpoint.

When an Intermediate Session is passed in, all relationship types - active_member, pending_member,invited_member, and eligible_to_join_by_email_domain - will be returned, and any membership can be assumed by calling the Exchange Intermediate Session endpoint.

This endpoint requires either an intermediate_session_token, session_jwt or session_token be included in the request. It will return an error if multiple are present.

Path parameters

intermediate_session_token string

The Intermediate Session Token. This token does not belong to a specific instance of a member, but may be exchanged for an existing Member Session or used to create a new organization.

session_token string

A secret token for a given Stytch Session. Read more about session_token in our Session Management guide.

session_jwt string

The JSON Web Token (JWT) for a given Stytch Session. Read more about session_jwt in our Session Management guide.

Response fields

status_code int

request_id string

email_address string

The email address.

discovered_organization array

An array of discovered_organization objects tied to the intermediate_session_token. See the Discovered Organization Object for complete details.

REQUEST

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

RESPONSE

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

Create Organization via Discovery

POSThttps://test.stytch.com/v1/b2b/discovery/organizations/create

If an end user does not want to join any already-existing organization, or has no possible organizations to join, this endpoint can be used to create a new Organization and Member. This endpoint can also be used to start an initial session for the newly created member and organization.

Body parameters

intermediate_session_token* string

The Intermediate Session Token. This token does not belong to a specific instance of a member, but may be exchanged for a Member Session or used to create a new organization.

session_duration_minutes int

session_custom_claims map<string, any>

organization_name* string

The name of the Organization.

organization_slug* string

The unique URL slug of the Organization. A minimnum of two characters is required. The slug only accepts alphanumeric characters and the following reserved characters: - . _ ~.

organization_logo_url string

The image URL of the Organization logo.

trusted_metadata object

An arbitrary JSON object for storing application-specific data.

email_jit_provisioning string

The authentication setting that controls how a new Member can be provisioned by authenticating via Email Magic Link. The accepted values are:

RESTRICTED – only new Members with verified emails that comply with email_allowed_domains can be provisioned upon authentication via Email Magic Link.

NOT_ALLOWED – disable JIT provisioning via Email Magic Link.

email_invites string

The authentication setting that controls how a new Member can be invited to an organization by email. The accepted values are:

ALL_ALLOWED – any new Member can be invited to join via email.

RESTRICTED – only new Members with verified emails that comply with email_allowed_domains can be invited via email.

NOT_ALLOWED – disable email invites.

email_allowed_domains array[strings]

An array of email domains that allow invites or JIT provisioning for new Members. This list is enforced when either email_invites or email_jit_provisioning is set to RESTRICTED.

Common domains such as gmail.com are not allowed. See the common email domains resource for the full list.

sso_jit_provisioning string

The authentication setting that controls the JIT provisioning of Members when authenticating via SSO. The accepted values are:

ALL_ALLOWED – new Members will be automatically provisioned upon successful authentication via any of the Organization's sso_active_connections.

RESTRICTED – only new Members with SSO logins that comply with sso_jit_provisioning_allowed_connections can be provisioned upon authentication.

NOT_ALLOWED – disable JIT provisioning via SSO.

Response fields

status_code int

request_id string

member_id string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

session_token string

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

session_jwt string

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

member_session object

member object

organization object

REQUEST

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

RESPONSE

{
	"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
	"status_code": 200,
	"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
	"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
	"session_jwt": "eyJ...",
    "member_session": {...},
    "member": {...},
    "organization": {...}
}

Exchange Intermediate Session

POSThttps://test.stytch.com/v1/b2b/discovery/intermediate_sessions/exchange

Exchange an Intermediate Session for a fully realized Member Session in a desired Organization.

This endpoint can be used to accept invites and create new members via domain matching.

Path parameters

intermediate_session_token* string

The Intermediate Session Token. This token does not belong to a specific instance of a member, but may be exchanged for a Member Session or used to create a new organization.

organization_id* string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

session_custom_claims map<string, any>

session_duration_minutes int

Response fields

status_code int

request_id string

member_id string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

session_token string

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

session_jwt string

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

member_session object

member object

organization object

REQUEST

curl --request GET \
	--url https://test.stytch.com/v1/b2b/intermediate_sessions/exchange \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"intermediate_session_token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
		"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
		"session_duration_minutes": 60
	}'

RESPONSE

{
	"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
	"status_code": 200,
	"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
	"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
	"session_jwt": "eyJ...",
    "member_session": {...},
    "member": {...},
    "organization": {...}
}

Passwords Overview

Password overview Stytch supports creating, storing, and authenticating password based members, as well as support for account recovery (password reset) and account deduplication with passwordless login methods.

For migrating existing password based members into Stytch, we support importing bcrypt, scrypt, argon2, MD-5, and SHA-1 password hashes from common auth providers like Cognito, Auth0, and Firebase.

Our implementation of passwords has built-in breach detection powered by HaveIBeenPwned on both sign-up and login, to prevent the use of compromised credentials and uses Dropbox’s zxcvbn strength requirements to guide members towards creating passwords that are easy for humans to remember but difficult for computers to crack.

Authenticate

POSThttps://test.stytch.com/v1/b2b/passwords/authenticate

Authenticate a member with their email address and password. This endpoint verifies that the member 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 member’s credentials appeared in the HaveIBeenPwned dataset.
- We force a password reset to ensure that the member is the legitimate owner of the email address, and not a malicious actor abusing the compromised credentials.
A member that has previously authenticated with email/password uses a passwordless authentication method tied to the same email address (e.g. Magic Links) for the first time. Any subsequent email/password authentication attempt will result in this error.
- We force a password reset in this instance in order to safely deduplicate the account by email address, without introducing the risk of a pre-hijack account takeover attack.
- Imagine a bad actor creates many accounts using passwords and the known email addresses of their victims. If a victim comes to the site and logs in for the first time with an email-based passwordless authentication method then both the victim and the bad actor have credentials to access to the same account. To prevent this, any further email/password login attempts first require a password reset which can only be accomplished by someone with access to the underlying email address.

Body parameters

organization_id* string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

email_address* string

The email address of the Member.

password* string

The password to authenticate

session_token string

session_jwt string

session_duration_minutes int

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

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

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

session_custom_claims map<string, any>

Response fields

status_code int

request_id string

member_session object

reset_sessions boolean

session_token string

A secret token for a given Stytch Session.

session_jwt string

The JSON Web Token (JWT) for a given Stytch Session.

organization_id string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

member object

organization object

REQUEST

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": "sandbox@stytch.com",
	  "password": "r@r2o19R(3$RzD@e",
	  "session_duration_minutes": 30
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
  "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
  "session_jwt": "example_jwt",
  "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
  "member_session": {...},
  "member": {...},
  "organization": {...}
}

Email reset start

POSThttps://test.stytch.com/v1/b2b/passwords/email/reset/start

Initiates a password reset for the email address provided. This will trigger an email to be sent to the address, containing a magic link that will allow them to set a new password and authenticate.

Body parameters

organization_id* string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

email_address* string

The email address of the member to start the email reset process for

reset_password_redirect_url string

The URL that the Member clicks from the reset password link. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's authenticate endpoint and finishes the reset password flow. If this value is not passed, the default reset_password_redirect_url that you set in your Dashboard is used. If you have not set a default reset_password_redirect_url, an error is returned.

login_redirect_url string

The URL that the Member clicks from the reset without password link. This URL should be an endpoint in the backend server that verifies the request by querying Stytch's authenticate endpoint and finishes the magic link flow. 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. This value is only used if magic links are enabled for the member.

reset_password_template_id string

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

locale string

Used to determine which language to use when sending the member an email. Currently only "EN" is supported, Spanish & Portuguese are coming soon.

reset_password_expiration_minutes int

Sets a time limit after which the email link to reset the member's password will no longer be valid.

Response fields

status_code int

request_id string

member_id string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

member_email_id string

Globally unique UUID that identifies a member's email

REQUEST

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": "sandbox@stytch.com",
	  "reset_password_redirect_url": "https://someexample.com",
      "login_redirect_url": "https://someexample.com",
      "reset_password_expiration_minutes": 10
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
  "member_email_id": "member-email-test-1dd089b3-8904-47ef-b943-987968e549d4",
  "member": {...}
}

Email reset

POSThttps://test.stytch.com/v1/b2b/passwords/email/reset

Reset the member's password and authenticate them. This endpoint checks that the password reset token is valid, hasn’t expired, or already been used.

The provided password needs to meet our password strength requirements, which can be checked in advance with the password strength endpoint. If the token and password are accepted, the password is securely stored for future authentication and the user is authenticated.

Body parameters

password_reset_token* string

The password reset token to authenticate.

password* string

The password to reset.

session_token string

session_jwt string

session_duration_minutes int

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

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

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

session_custom_claims map<string, any>

code_verifier string

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

Response fields

request_id string

status_code int

member_id string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

member_session object

session_token string

A secret token for a given Stytch Session.

session_jwt string

The JSON Web Token (JWT) for a given Stytch Session.

organization_id string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

member object

organization object

REQUEST

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": "r@r2o19R(3$RzD@e"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
  "member_email_id": "member-email-test-1dd089b3-8904-47ef-b943-987968e549d4",
  "member": {...}
}

Existing reset

POSThttps://test.stytch.com/v1/b2b/passwords/existing_password/reset

Reset the member’s password using their existing password.

Body parameters

organization_id* string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

email_address* string

The email address of the Member.

existing_password* string

The member's current password that they supplied.

new_password* string

The member's elected new password.

session_token string

A secret token for a given Stytch Session.

session_jwt string

The JSON Web Token (JWT) for a given Stytch Session.

session_custom_claims map<string, any>

session_duration_minutes int

Response fields

member_id string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

member object

organization object

status_code int

request_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/b2b/passwords/existing_password/reset \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	  "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
	  "email_address": "sandbox@stytch.com",
	  "existing_password": "old_password",
	  "new_password": "r@r2o19R(3$RzD@e"
	}'

RESPONSE

{
    "member": {...},
    "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
    "member_session": {...},
    "organization": {...}
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "session_jwt": "example_jwt",
    "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
    "status_code": 200
}

Session reset

POSThttps://test.stytch.com/v1/b2b/passwords/session/reset

This API allows you to check whether the user’s provided password is valid, and to provide feedback to the user on how to increase the strength of their password.

This endpoint adapts to your Project's password strength configuration. If you're using zxcvbn, the default, your passwords are considered valid if the strength score is >= 3. If you're using LUDS, your passwords are considered valid if they meet the requirements that you've set with Stytch. Reach out to support@stytch.com if you'd like to change your password strength configuration.

Body parameters

organization_id* string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

email_address* string

The email address of the Member.

password* string

The password to authenticate

session_token string

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

session_jwt string

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

Response fields

status_code int

request_id string

member_session object

member object

REQUEST

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": "r@r2o19R(3$RzD@e"
	  "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q"
	}'

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
  "member_session": {...},
  "member": {...},
}

Delete password

DELETEhttps://test.stytch.com/v1/b2b/organizations/{organization_id}/members/passwords/{member_password_id}

Delete a member's password.

Path parameters

organization_id* string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

member_password_id* string

The ID of the password to be deleted.

Response fields

member_id string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

member object

organization object

status_code int

request_id string

REQUEST

curl --request DELETE \
	--url https://test.stytch.com/v1/b2b/organizations/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931/members/passwords/member-password-test-51861cbc-d3b9-428b-9761-227f5fb12be9 \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json'

RESPONSE

{
    "member": {...},
    "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
    "organization": {...}
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "status_code": 200
}

Strength check

POSThttps://test.stytch.com/v1/b2b/passwords/strength_check

This API allows you to check whether the user’s provided password is valid, and to provide feedback to the user on how to increase the strength of their password.

Password feedback

The zxcvbn_feedback and luds_feedback objects contains relevant fields for you to relay feedback to users that failed to create a strong enough password.

If you're using zxcvbn, the feedback object will contain warning and suggestions for any password that does not meet the zxcvbn strength requirements. You can return these strings directly to the user to help them craft a strong password.

If you're using LUDS, the feedback object will contain a collection of fields that the user failed or passed. You'll want to prompt the user to create a password that meets all requirements that they failed.

Body parameters

password* string

The password to be strength tested

email_address string

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

Response fields

status_code int

request_id string

breach_detection_on_create boolean

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

breached_password boolean

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

luds_feedback object

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

Collapse

luds_requirements object

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

Collapse

has_digit boolean

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

has_lower_case boolean

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

has_symbol boolean

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

has_upper_case boolean

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

missing_characters integer

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

missing_complexity integer

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

zxcvbn_feedback object

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

Collapse

suggestions array

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

warning string

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

score int

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

strength_policy string

The strength policy type enforced, either zxcvbn or luds.

valid_password boolean

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

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/b2b/passwords/strength_check \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	  "password": "r@r2o19R(3$RzD@e"
	}'

RESPONSE

{
    "breach_detection_on_create": true,
    "breached_password": false,
    "luds_feedback": {},
    "request_id": "request-id-test-f3aca0eb-e38f-4e0a-b5cc-e6e52ad88c71",
    "score": 0,
    "status_code": 200,
    "strength_policy": "zxcvbn",
    "valid_password": false,
    "zxcvbn_feedback": {
        "suggestions": [
            "Add another word or two. Uncommon words are better."
        ],
        "warning": ""
    }
}

Migrate

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

Adds an existing password to a member's email that doesn't have a password yet. We support migrating members from passwords stored with bcrypt, scrypt, argon2, MD-5, and SHA-1. This endpoint has a rate limit of 10 requests per second.

Body parameters

organization_id* string

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value.

email_address* string

The email address of the Member.

hash* string

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

hash_type* string

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

scrypt_config object

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

Collapse

salt string

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

n_parameter int

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

r_parameter int

The r parameter, also known as the block size.

p_parameter int

The p parameter, also known as the parallelism factor.

key_length int

The key length, also known as the hash length.

argon_2_config object

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

Collapse

salt string

The salt value.

iteration_amount int

The iteration amount.

memory int

The memory in kibibytes.

threads int

The thread value, also known as the parallelism factor.

key_length int

The key length, also known as the hash length.

md_5_config object

Optional parameters for MD-5 hash types.

Collapse

prepend_salt string

The salt that should be prepended to the migrated password.

append_salt string

The salt that should be appended to the migrated password.

sha_1_config object

Optional parameters for SHA-1 hash types.

Collapse

prepend_salt string

The salt that should be prepended to the migrated password.

append_salt string

The salt that should be appended to the migrated password.

Response fields

member_id string

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value.

member object

organization object

status_code int

request_id string

REQUEST

curl --request POST \
	--url https://test.stytch.com/v1/b2b/passwords/migrate \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "email_address": "sandbox@stytch.com",
    "hash": "$2b$04$oa70000TFDu3icElr2qML7Le",
    "hash_type": "bcrypt"
  }'

RESPONSE

{
	"connection": {
		"acs_url":  "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"attribute_mapping": {
			"email": "email",
			"full_name": "name",
		},
		"audience_uri":  "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"connection_id": "saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"display_name": "",
		"idp": "",
		"idp_entity_id": "",
		"idp_sso_url": "",
		"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
		"signing_certificates": [
			{
				"certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE",
				"id": "",
				"created_at": "2023-01-01T00:00:00Z",
				"expires_at": "2033-01-01T00:00:00Z",
				"issuer": "Stytch"
			}
		],
		"status": "pending",
		"verification_certificates": []
	},
	"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
	"status_code": 200
}

Resources Overview

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

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

Organization authentication settings

Every Organization has a set of fields that control the authentication and provisioning of its Members. These controls have admin-like capabilities and should be updated deliberately.

The Organization auth settings are grouped by type of auth factor. The auth setting field names are prepended with an auth factor like email or sso or oauth. For example, all Organization fields that begin with email_* are settings that specifically affect provisioning and auth flows via Email Magic Links.

An Organization must always have at least one auth setting that allows new Members to be created and join. As a result, sso_jit_provisioning, email_jit_provisioning, email_invites cannot all be simultaneously set to NOT_ALLOWED.

Here is an example Organization object with its auth settings fully shown.

{
    "organization_name": "Example Org",
    "organization_slug": "example-org",
   
    // Auth settings for Email Magic Links
    "email_invites": "NOT_ALLOWED" | "RESTRICTED" | "ALL_ALLOWED",    
    "email_jit_provisioning": "NOT_ALLOWED" | "RESTRICTED",
    "email_allowed_domains": ["stytch.com"],

    // Auth settings for Single Sign On
    "sso_jit_provisioning": "NOT_ALLOWED" | "RESTRICTED" | "ALL_ALLOWED",
    "sso_default_connection_id": "...",
    "sso_jit_provisioning_allowed_connections": [
        "saml-connection-live-7111f7b1-9896-4ce3-a658-9e0707fc5192",
    ],
    "sso_active_connections": [
        { "connection_id": … },
        { "connection_id": … }      
    ]

    …
}

Auth settings for Email Magic Links:

If email_allowed_domains is empty
- then email_invites cannot be set to RESTRICTED.
- then email_jit_provisioning cannot be set to RESTRICTED.
If email_allowed_domains is not empty
- and email_invites is set to RESTRICTED, then all new Members must have an email address that complies with email_allowed_domains in order to be invited by email.
- and email_invites is set to ALL_ALLOWED, then any new Member can be invited to email.
- and email_invites is set to NOT_ALLOWED, then email invites are disabled.
If email_allowed_domains is not empty
- and email_jit_provisioning is set to RESTRICTED, then all new Members must have an email address that complies with email_allowed_domains in order to be provisioned via Email Magic Links.
- and email_jit_provisioning is set to ALL_ALLOWED, then any new Member can be provisioned via Email Magic Links.
- and email_jit_provisioning is set to NOT_ALLOWED, then JIT provisioning via Email Magic Links is disabled.
If email_allowed_domains is updated
- then the entire list will be overwritten by the new value.
- then all Members will remain active even if their email_address no longer complies with email_allowed_domains.
- and either email_invites or email_jit_provisioning is set to RESTRICTED, then email_allowed_domains cannot be set to an empty array.

Auth settings for Single Sign On:

If sso_jit_provisioning_allowed_connections is empty
- then sso_jit_provisioning cannot be set to RESTRICTED.
If sso_jit_provisioning_allowed_connections is not empty
- and sso_jit_provisioning is set to RESTRICTED, then all new Members must have an SSO login that complies with sso_jit_provisioning_allowed_connections in order to be provisioned via SSO.
- and sso_jit_provisioning is set to ALL_ALLOWED, then all new Members will be automatically provisioned via any of the Organization's sso_active_connections.
- and sso_jit_provisioning is set to NOT_ALLOWED, then JIT provisioning via SSO is disabled.
If sso_jit_provisioning_allowed_connections is updated
- then the entire list will be overwritten by the new value.
- then all currently active Members will remain active even if their sso_registrations no longer complies with sso_jit_provisioning_allowed_connections.
- and sso_jit_provisioning is set to RESTRICTED, then sso_jit_provisioning_allowed_connections cannot be set to an empty array.

Common email domains

An Organization cannot have a certain set of common email domains added to email_allowed_domains. The following email domains are not allowed:

gmail, aol, yahoo, icloud, hotmail, msn, comcast, live, outlook, att, earthlink, me, mac, sbcglobal, verizon, ig, mail, hey, laposte, wanadoo, googlemail, orange, rediffmail, uol, bol, free, gmx, yandex, ymail, libero

Member states

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

active: Members become active after successfully authenticating at least once via Stytch. When the SendLoginOrSignup endpoint is called on an active Member, they will receive a login email template. The Email Magic Link will route them to the login_redirect_url provided in the request.

pending: Stytch Members are created as pending when created by the SendLoginOrSignup endpoint or when they are created by the CreateMember endpoint with the create_member_as_pending parameter set to true. If the SendInviteEmail endpoint is called on a pending Member, their status will change to invited. Once a Member successfully authenticates a Magic Link from either an invite or signup email, they will be marked as active.

invited: Stytch Members are created as invited when created by the SendInviteEmail endpoint. The invited Member will receive an email that uses the invite email template. If the SendLoginOrSignup endpoint is called on an already invited member, their status will stay invited. Once a Member successfully authenticates a Magic Link from either an invite or signup email, they will be marked as active.

deleted: Stytch Members are marked as deleted after calling the DeleteMember or DeleteOrganization endpoint. Once a Member is deleted, any emails or auth factors tied to that Member are also deleted. The SearchMember endpoint will not return deleted Members.

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 tied to, for example member-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6 belongs to the test environment.

Email templates

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

Metadata

Stytch Members may contain metadata - arbitrary JSON objects for recording application-specific information.

Metadata restrictions

Metadata objects may contain a maximum of 20 top-level keys.
Metadata objects cannot exceed 4KB in size

Metadata permissions

Stytch Members contain two types of metadata - trusted_metadata and untrusted_metadata.

Direct API integrations can read and write to both trusted_metadata and untrusted_metadata.

Frontend SDK integrations can read and write to untrusted_metadata, but only read trusted_metadata.

Secure fields, such as a Member's role, billing_status, or stripe_customer_id should only be stored in trusted_metadata by using a direct API integration. Fields that a Member can be allowed to edit directly - such as display_theme or preferred_locale may be stored in untrusted_metadata.

Do not store any sensitive information (passport numbers, credit card details, etc.) as metadata.

Metadata update behavior

Metadata update payloads will be merged with the existing metadata at the top level only. Send a top-level value of null to delete an existing field. To delete all metadata from an object, send a top-level value of null for every existing field. Stytch will not merge deeply nested objects or arrays. To add a field to a deeply nested object, or update an array, replace the entire top-level key.

Example: adding a new field

Initial:

{
  "trusted_metadata": {
    "key1": "value1"
  }
}

Update:

{
  "trusted_metadata": {
    "key2": "value2"
  }
}

Result:

{
  "trusted_metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}

Example: replacing an existing field

Initial:

{
  "untrusted_metadata": {
    "key1": "value1"
  }
}

Update:

{
  "untrusted_metadata": {
    "key1": "value2"
  }
}

Result:

{
  "untrusted_metadata": {
    "key1": "value2"
  }
}

Example: updating a deeply nested field

Initial:

{
  "trusted_metadata": {
    "key1": [{"deep": "value1"}],
    "other_key": "other_value"
  }
}

Update:

{
  "trusted_metadata": {
    "key1": [{"deep": "value1"}, {"deep": "value2"}]
  }
}

Result:

{
  "trusted_metadata": {
    "key1": [{"deep": "value1"}, {"deep": "value2"}],
    "other_key": "other_value"
  }
}

Example: deleting a field

Initial:

{
  "untrusted_metadata": {
    "key1": [{"deep": "value1"}],
    "other_key": "other_value"
  }
}

Update:

{
  "untrusted_metadata": {
    "key1": null
  }
}

Result:

{
  "untrusted_metadata": {
    "other_key": "other_value"
  }
}

Example: deleting all fields

Initial:

{
  "trusted_metadata": {
    "key1": [{"deep": "value1"}],
    "other_key": "other_value"
  }
}

Update:

{
  "trusted_metadata": {
    "key1": null,
    "other_key": null
  }
}

Result:

{
  "trusted_metadata": {}
}

URL validation

To ensure your Members 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.

SAML SSO Overview

Stytch allows your organizations to use SAML SSO as an authentication method. Stytch will act as the Service Provider (SP) in front of your organizations, and interface with the Identity Provider (IdP), which will provide authentication assertions.

Attribute mappings:

Stytch requires any identity provider to specify the email and name of the member attempting to log in. It parses these from the attributes sent in the IdP's assertion to Stytch. To recognize which attributes correspond to which fields, Stytch allows your connection to define an attribute_mapping.

An example attribute_mapping looks like this:

	"attribute_mapping": {
		"email": "email",
		"full_name": "name"
	},

Stytch requires either the full_name key to be present, or both the first_name and last_name keys. Additionally, Stytch requires an email key to be present if the NameID format sent by the IdP is not an email.

The attribute mapping can be set in the Update SAML Connection endpoint.

Single sign-on URLs:

Some IdPs may ask for a single sign-on URL. This is listed as the acs_url in the SAML connection object. Note that for Stytch's purposes, the acs_url and audience_uri are the same value.

Signing and Verification Certificates

Signing Certificates

When sending an authentication request to the IdP, Stytch sends a signature along with the request, indicating that the request came from Stytch. This signature can be verified using the Signing Certificate provided by Stytch, in the form of an X.509 certificate. This certificate is present on all SAML connection objects.

Some IdPs may call this a "signed request" or "Signature Validation", or have WantAuthnRequestsSigned="true" in their SAML configuration settings. This certificate should be uploaded to the IdP in order to make use of this optional feature.

Verification Certificates

When receiving an authentication response from the IdP, Stytch will verify that the response actually originates from the IdP.

Stytch will only accept an authentication response from the IdP if the signature of the response is correctly validated with the connection's stored Verification Certificate, which comes from the IdP. This X.509 certificate is uploaded to Stytch and stored with the specific SAML connection. In the API, you can provide the certificate on a SAML update request.

There is a limit of 5 verification certificates per SAML connection. You can delete a connection's certificate by calling the Delete Verification Certificate. endpoint.

When uploading a certificate to an IdP or passing a certificate to Stytch, you may encounter the certificate in the form of a PEM file. If you are manually taking a certificate from Stytch's Create SAML Connection endpoint, you can save it as a PEM file as so:

echo "-----BEGIN CERTIFICATE-----\nMIIFIjCCAwoCCQC8brjOdUXVjTANBgkqhkiG9w0BAQsFADBTMQswCQYDVQQGEwJV\nUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzEX\n...more base64 here...\n9A7Yts1LcBX0kX91G2I++0JRMM0E5OwnG6MXtPJfmsLmPM3WkJHGf2PUY6k6xR+y\nokXHOYlhkarZ3SKPVUWE5rpK4GtpYEOaLIrDAxRm2qm4NvDN7zuz51RhHh9DcP4v\nQWz1JJ4v5Q63z2Mz8sIxDoWzxw9wl9wVq0u5QN2jP2cxGvdTG4rGTpZW5AT3LBWa\nvgej5xjwiYfaoboTEHQE8iP+EPwtCA==\n-----END CERTIFICATE-----\n" > stytch_signing_certificate.pem

Note that the API returns the signing certificate as a raw string (with newlines).

OBJECT

Errors overview

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.

Error object

Fields

status_code int

The HTTP status code of the error.

request_id string

error_type string

The name of the error and its type.

error_message string

A description of the error and what caused it.

error_url string

A link to Stytch Docs with more resources to help debug the error.

OBJECT

{
  "status_code": 403,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "use_https",
  "error_message": "Please use https instead of http.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/403/use_https"
}

400 errors

active_totp_exists

400Bad request

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.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "active_totp_exists",
  "error_message": "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.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/active_totp_exists"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

apple_oauth_config_not_found

400Bad request

The Apple OAuth config was not found.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "apple_oauth_config_not_found",
  "error_message": "The Apple OAuth config was not found.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/apple_oauth_config_not_found"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

argon_2_key_length_mismatch

400Bad request

The key_length value doesn't match the length of the provided hash.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "argon_2_key_length_mismatch",
  "error_message": "The key_length value doesn't match the length of the provided hash.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/argon_2_key_length_mismatch"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

bad_request

400Bad request

The submitted request is invalid.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "bad_request",
  "error_message": "The submitted request is invalid.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/bad_request"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

billing_not_verified

400Bad request

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.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "billing_not_verified",
  "error_message": "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 https://stytch.com/settings/billing to provide billing information.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/billing_not_verified"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

billing_not_verified_for_email

400Bad request

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.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "billing_not_verified_for_email",
  "error_message": "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 https://stytch.com/settings/billing to provide billing information.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/billing_not_verified_for_email"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

cannot_delete_default_sso_connection

400Bad request

Please update the default SSO connection setting for this organization to a different SSO connection before deleting.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "cannot_delete_default_sso_connection",
  "error_message": "Please update the default SSO connection setting for this organization to a different SSO connection before deleting.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/cannot_delete_default_sso_connection"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

cannot_delete_email

400Bad request

Cannot delete the last email for a user with a password. This ensures they can complete a password reset.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "cannot_delete_email",
  "error_message": "Cannot delete the last email for a user with a password. This ensures they can complete a password reset.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/cannot_delete_email"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

cannot_delete_last_primary_factor

400Bad request

You cannot delete the last primary factor (email, phone number, crypto wallet) for a user because that would make their account difficult or impossible to recover. If you want to remove the user from your project, delete the user instead.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "cannot_delete_last_primary_factor",
  "error_message": "Cannot delete the last primary factor (email, phone number, crypto wallet) for a user. If you want to delete the user instead, use the DeleteUser endpoint: https://stytch.com/docs/api/delete-user",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/cannot_delete_last_primary_factor"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

cannot_delete_last_sso_verification_key

400Bad request

Cannot delete the last verification certificate for a connection. Please pass in another one before deleting this one.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "cannot_delete_last_sso_verification_key",
  "error_message": "Cannot delete the last verification certificate for a connection. Please pass in another one before deleting this one.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/cannot_delete_last_sso_verification_key"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

cannot_reset_password_with_existing_password

400Bad request

Cannot reset user's password using their existing password. This could be because their existing password was part of a data breach or to prevent password squatting. Please reset the password via a session or email reset.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "cannot_reset_password_with_existing_password",
  "error_message": "Cannot reset user's password using their existing password. This could be because their existing password was part of a data breach or to prevent password squatting. Please reset the password via a session or email reset.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/cannot_reset_password_with_existing_password"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

cannot_use_webauthn_with_pending_user

400Bad request

WebAuthn can only be used with active users. To learn more about WebAuthn and user states please see here and here.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "cannot_use_webauthn_with_pending_user",
  "error_message": "WebAuthn can only be used for active users. To learn more about WebAuthn and user states read more at https://stytch.com/docs/api/webauthn-overview and https://stytch.com/docs/api/user-states.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/cannot_use_webauthn_with_pending_user"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

client_secret_too_long

400Bad request

Client secret is too long. Please make sure you have the correct value.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "client_secret_too_long",
  "error_message": "Client secret is too long. Please make sure you have the correct value.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/client_secret_too_long"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

custom_claims_too_large

400Bad request

Custom claims are too large.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "custom_claims_too_large",
  "error_message": "Custom claims are too large.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/custom_claims_too_large"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

deprecated_endpoint

400Bad request

This endpoint has been deprecated

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "deprecated_endpoint",
  "error_message": "This endpoint has been deprecated",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/deprecated_endpoint"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

duplicate_email

400Bad request

A user with the specified email already exists for this project.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "duplicate_email",
  "error_message": "A user with the specified email already exists for this project.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/duplicate_email"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

duplicate_email_for_user

400Bad request

The specified email is already tied to this user.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "duplicate_email_for_user",
  "error_message": "The specified email is already tied to this user.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/duplicate_email_for_user"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

duplicate_email_template_vanity_id

400Bad request

Email template vanity ID already exists.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "duplicate_email_template_vanity_id",
  "error_message": "Email template vanity ID already exists.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/duplicate_email_template_vanity_id"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

duplicate_member_email

400Bad request

This email already exists for this organization.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "duplicate_member_email",
  "error_message": "This email already exists for this organization.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/duplicate_member_email"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

duplicate_organization

400Bad request

An organization with the specified name already exists.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "duplicate_organization",
  "error_message": "An organization with the specified name already exists.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/duplicate_organization"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

duplicate_organization_user

400Bad request

A user with the specified email already exists for this organization.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "duplicate_organization_user",
  "error_message": "A user with the specified email already exists for this organization.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/duplicate_organization_user"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

duplicate_project_user

400Bad request

A project user for the specified organization user already exists for this project.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "duplicate_project_user",
  "error_message": "A project user for the specified organization user already exists for this project.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/duplicate_project_user"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

duplicate_redirect_url

400Bad request

A redirect URL already exists for the provided URL.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "duplicate_redirect_url",
  "error_message": "A redirect URL already exists for the provided URL.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/duplicate_redirect_url"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

duplicate_saml_connection

400Bad request

The SAML connection already exists for this organization and IDP.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "duplicate_saml_connection",
  "error_message": "The SAML connection already exists for this organization and IDP.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/duplicate_saml_connection"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

duplicate_saml_response

400Bad request

This SAML response has already been seen. Please attempt to log in again.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "duplicate_saml_response",
  "error_message": "This SAML response has already been seen. Please attempt to log in again.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/duplicate_saml_response"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

duplicate_webauthn_registration

400Bad request

The supplied credential ID already exists for this project.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "duplicate_webauthn_registration",
  "error_message": "The supplied credential ID already exists for this project.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/duplicate_webauthn_registration"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

expired_saml_response

400Bad request

Too much time has passed since the login flow started. Please attempt to log in again.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "expired_saml_response",
  "error_message": "Too much time has passed since the login flow started. Please attempt to log in again.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/expired_saml_response"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

expired_totp

400Bad request

The TOTP for this user has expired without being verified.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "expired_totp",
  "error_message": "The TOTP for this user has expired without being verified.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/expired_totp"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

failed_saml_response

400Bad request

The user failed to log in to their IDP, or the IDP failed to authenticate the application.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "failed_saml_response",
  "error_message": "The user failed to log in to their IDP, or the IDP failed to authenticate the application.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/failed_saml_response"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

id_token_expired

400Bad request

ID token is expired.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "id_token_expired",
  "error_message": "ID token is expired.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/id_token_expired"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

id_token_incorrect_audience

400Bad request

ID token's audience does not match the OAuth configuration's ID.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "id_token_incorrect_audience",
  "error_message": "ID token's audience does not match the OAuth configuration's ID.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/id_token_incorrect_audience"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

id_token_invalid

400Bad request

ID token is invalid.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "id_token_invalid",
  "error_message": "ID token is invalid.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/id_token_invalid"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

id_token_nonce_invalid

400Bad request

The provided nonce does not match the nonce in the ID token.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "id_token_nonce_invalid",
  "error_message": "The provided nonce does not match the nonce in the ID token.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/id_token_nonce_invalid"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

inactive_email

400Bad request

The email provided has been marked as inactive by our email provider. This happens most often when the email is undeliverable due to a hard bounce.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "inactive_email",
  "error_message": "The email provided has been marked as inactive by our email provider. This happens most often when the email is undeliverable due to a hard bounce.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/inactive_email"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

indeterminate_sso_connection_for_organization

400Bad request

The organization owns more than one SSO Connection. Please specify the specific connection to be used.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "indeterminate_sso_connection_for_organization",
  "error_message": "The organization owns more than one SSO Connection. Please specify the specific connection to be used.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/indeterminate_sso_connection_for_organization"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

invalid_append_salt

400Bad request

The append_salt value is not supported because it's too long.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "invalid_append_salt",
  "error_message": "The append_salt value is not supported because it's too long.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/invalid_append_salt"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

invalid_argon_2_iteration_amount

400Bad request

The iteration_amount value is invalid.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "invalid_argon_2_iteration_amount",
  "error_message": "The iteration_amount value is invalid.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/invalid_argon_2_iteration_amount"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

invalid_argon_2_key_length

400Bad request

The key_length value is invalid.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "invalid_argon_2_key_length",
  "error_message": "The key_length value is invalid.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/invalid_argon_2_key_length"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

invalid_argon_2_memory

400Bad request

The memory value is invalid.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "invalid_argon_2_memory",
  "error_message": "The memory value is invalid.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/invalid_argon_2_memory"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

invalid_argon_2_salt

400Bad request

The salt value is an unsupported length.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "invalid_argon_2_salt",
  "error_message": "The salt value is an unsupported length.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/invalid_argon_2_salt"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

invalid_argon_2_threads

400Bad request

The threads value is invalid.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "invalid_argon_2_threads",
  "error_message": "The threads value is invalid.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/invalid_argon_2_threads"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

invalid_argument

400Bad request

Invalid argument.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "invalid_argument",
  "error_message": "Invalid argument.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/invalid_argument"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

invalid_audience_saml_response

400Bad request

The audience in the SAML response is incorrect.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "invalid_audience_saml_response",
  "error_message": "The audience in the SAML response is incorrect.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/invalid_audience_saml_response"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

invalid_authentication_type

400Bad request

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.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "invalid_authentication_type",
  "error_message": "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: https://stytch.com/docs/api/authentication",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/invalid_authentication_type"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

invalid_authenticator_type

400Bad request

Invalid authenticator type. The valid values are platform and cross-platform.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "invalid_authenticator_type",
  "error_message": "Invalid authenticator type. The valid values are platform and cross-platform.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/invalid_authenticator_type"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

invalid_authorization_header

400Bad request

The authorization header provided with the request is invalid.

Common causes

HTTP request is missing an Authorization header
The Authorization header in the HTTP request is not formatted properly
The Authorization header in the HTTP request has the incorrect credentials

Troubleshooting steps

Check the Authorization header in the HTTP request for proper formatting.
Always use the Basic Auth type in the header.
Check the project credentials you entered match your API keys in the Dashboard.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "invalid_authorization_header",
  "error_message": "The authorization header provided with the request is invalid.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/invalid_authorization_header"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

invalid_base64_scrypt_hash

400Bad request

The provided hash isn't a base64 encoded string. Please base64 encode the hash before passing it to this endpoint.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "invalid_base64_scrypt_hash",
  "error_message": "The provided hash isn't a base64 encoded string. Please base64 encode the hash before passing it to this endpoint.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/invalid_base64_scrypt_hash"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

invalid_base64_scrypt_salt

400Bad request

The provided salt isn't a base64 encoded string. Please base64 encode the salt before passing it to this endpoint.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "invalid_base64_scrypt_salt",
  "error_message": "The provided salt isn't a base64 encoded string. Please base64 encode the salt before passing it to this endpoint.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/invalid_base64_scrypt_salt"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

invalid_bcrypt_cost

400Bad request

The bcrypt cost value is too high, it must be less than 15. If you need a higher cost parameter, please email support@stytch.com.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "invalid_bcrypt_cost",
  "error_message": "The bcrypt cost value is too high, it must be less than 15. If you need a higher cost parameter, please email support@stytch.com.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/invalid_bcrypt_cost"
}

How to get help

Visit our forum

Send us an email

Ask in Slack

invalid_bcrypt_hash

400Bad request

The bcrypt hash passed is not valid.

Error

{
  "status_code": 400,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "invalid_bcrypt_hash",
  "error_message": "The bcrypt hash passed is not valid.",
  "error_url": "https://stytch.com/docs/b2b/api/errors/400/invalid_bcrypt_hash"
}

How to get help

Visit our forum

Send us an email

Ask in Slack