B2B API Reference

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

All B2B API resources are scoped to the Project of the API keys you provide.


Organization object


Fields


organization_idstring

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.


organization_slugstring

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_urlstring

The image URL of the Organization logo.


organization_namestring

The name of the Organization.


trusted_metadataobject

An arbitrary JSON object for storing application-specific data.


email_invitesstring

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_jit_provisioningstring

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_allowed_domainsarray[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_idstring

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


sso_jit_provisioningstring

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_active_connectionsarray[objects]

An array of active SAML Connection references.


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

OBJECT

200
{
  "organization": {
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "organization_name": "Example Org Inc.",
    "organization_slug": "example-org",
    "organization_logo_url": "",
    "email_allowed_domains": ["stytch.com"],
    "email_invites": "ALL_ALLOWED",
    "email_jit_provisioning": "RESTRICTED",
    "sso_default_connection_id": "saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
    "sso_jit_provisioning": "ALL_ALLOWED",
    "sso_jit_provisioning_allowed_connections": [
      "saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9"
    ],
    "sso_active_connections": [{
      "connection_id": "saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
      "display_name": "SSO test connection with IdP"
    }],
    "trusted_metadata": {
      "address": {
        "street": "1 Telegraph Hill Blvd",
        "city": "San Francisco",
        "state": "CA",
        "zip_code": "94133"
      },
      "billing_tier": "free"
    }
  }
}

Create an Organization

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

Creates an Organization. An organization_name and a unique organization_slug are required.

By default, email_invites will be set to ALL_ALLOWED if no Organization authentication settings are explicitly defined in the request.

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


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_urlstring

The image URL of the Organization logo.


trusted_metadataobject

An arbitrary JSON object for storing application-specific data.


email_jit_provisioningstring

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_invitesstring

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_domainsarray[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_provisioningstring

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


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


organizationobject

The Organization object.

REQUEST

Node
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

200
{
  "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_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


organizationobject

The Organization object.

REQUEST

Node
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

200
{
  "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_namestring

The name of the Organization.


organization_slugstring

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_urlstring

The image URL of the Organization logo.


trusted_metadataobject

An arbitrary JSON object for storing application-specific data.


email_jit_provisioningstring

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_invitesstring

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_domainsarray[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_idstring

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


sso_jit_provisioningstring

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_connectionsarray[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_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


organizationobject

The Organization object.

REQUEST

Node
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

200
{
  "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


cursorstring

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.


limitint

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.


queryobject

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


operatorstring

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.


operandsarray[objects]

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

Collapse


filter_namestring

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_valuestring or array

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

Collapse


organization_idsarray[strings]

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


organization_slugsarray[strings]

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


organization_slug_fuzzystring

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


organization_name_fuzzystring

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


member_emailsarray[strings]

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


member_email_fuzzystring

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


allowed_domainsarray[strings]

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


allowed_domain_fuzzystring

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


results_metadataobject

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

Collapse


next_cursorstring

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.


totalint

The total number of results that match your query.


Response fields


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


organizationsarray[objects]

An array of Organization objects.

REQUEST

Node
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

200
{
  "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_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


organization_idstring

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

Node
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

200
{
  "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_idstring

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_idstring

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_addressstring

The email address of the Member.


statusstring

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


namestring

The name of the Member.


trusted_metadataobject

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


untrusted_metadataobject

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_registrationsarray[objects]

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

Collapse


connection_idstring

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


registration_idstring

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


external_idstring

The id given by the identity provider.


sso_attributesobject

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

OBJECT

200
{
	"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.


namestring

The name of the Member.


trusted_metadataobject

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


untrusted_metadataobject

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.


create_member_as_pendingboolean

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_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


member_idstring

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.


memberobject

The Member object.

REQUEST

Node
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

200
{
  "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


namestring

The name of the Member.


trusted_metadataobject

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


untrusted_metadataobject

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.


Response fields


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


member_idstring

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.


memberobject

The Member object.

REQUEST

Node
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

200
{
  "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.


cursorstring

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.


limitint

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.


queryobject

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


operatorstring

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.


operandsarray[objects]

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

Collapse


filter_namestring

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


filter_valuestring or array

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

Collapse


member_idsarray[strings]

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


member_emailsarray[strings]

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


member_email_fuzzystring

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


statusesarray[strings]

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


results_metadataobject

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

Collapse


next_cursorstring

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.


totalint

The total number of results that match your query.


Response fields


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


membersarray[objects]

An array of Member objects.

REQUEST

Node
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

200
{
  "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_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


member_idstring

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

Node
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

200
{
  "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_urlstring

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_urlstring

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_challengestring

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_idstring

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_idstring

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_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


member_idstring

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_createdboolean

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


memberobject

The Member object.


organizationobject

The Organization object.

REQUEST

Node
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

200
{
  "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_urlstring

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_idstring

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_idstring

The member_id of the Member who sends the invite.


namestring

The name of the Member.


trusted_metadataobject

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


untrusted_metadataobject

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.


Response fields


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


member_idstring

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.


memberobject

The Member object.


organizationobject

The Organization object.

REQUEST

Node
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

200
{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f"
  "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_urlstring

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_challengestring

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_idstring

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_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.

REQUEST

Node
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

200
{
	"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_verifierstring

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


Response fields


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


intermediate_session_tokenstring

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_addressstring

The email address.


discovered_organizationarray

REQUEST

Node
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

200
{
	"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_idstring

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_idstring

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_attimestamp

The timestamp when the Session started.


last_accessed_attimestamp

The timestamp when the Session was last accessed.


expires_attimestamp

The timestamp when the Session will expire.


authentication_factorsarray[objects]

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


custom_claimsobject

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

200
{
  "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_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


member_sessionsarray[object]

An array of Session objects.

REQUEST

Node
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

200
{
	"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_tokenstring

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


session_jwtstring

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


session_duration_minutesint

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_claimsobject

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_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


member_sessionobject

The Session object.


session_tokenstring

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


session_jwtstring

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


memberobject

The Member object.


organizationobject

The Organization object.

REQUEST

Node
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

200
{
	"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_idstring

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_tokenstring

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


session_jwtstring

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


Response fields


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


member_idstring

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_tokenstring

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


session_jwtstring

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


member_sessionobject

The Session object.


memberobject

The Member object.


organizationobject

The Organization object.

REQUEST

Node
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

200
{
	"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_idstring

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_tokenstring

A secret token for a given Stytch Session.


session_jwtstring

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


member_idstring

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_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.

REQUEST

Node
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

200
{
  "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_idstring

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_idstring

Globally unique UUID that identifies a specific SAML Connection.


display_namestring

A human-readable display name for the connection.


acs_urlstring

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_uristring

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_mappingobject

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_idstring

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


idp_sso_urlstring

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


signing_certificatesarray

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

Expand


verification_certificatesarray

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

Expand


statusstring

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

OBJECT

200
{
  "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_idstring

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_namestring

A human-readable display name for the connection.


Response fields


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


connectionobject

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

REQUEST

Node
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

200
{
	"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_idstring

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_idstring

Globally unique UUID that identifies a specific SAML Connection.


Body parameters


idp_entity_idstring

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


display_namestring

A human-readable name to identify your SAML connection.


attribute_mappingobject

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.

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_namestring

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_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


connectionobject

Expand

REQUEST

Node
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

201
{
  "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_idstring

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_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


saml_connectionsarray[Object]

REQUEST

Node
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

200
{
  "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_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


connection_idstring

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

REQUEST

Node
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

200
{
  "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_challengestring

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_urlstring

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_urlstring

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_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


redirect_urlstring

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

REQUEST

Node
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

302
{
  "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_claimsmap<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_minutesint

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_jwtstring

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


session_tokenstring

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


pkce_code_verifierstring

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


Response fields


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


member_idstring

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_idstring

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.


memberobject

The Member object.


organizationobject

The Organization object.


session_tokenstring

A secret token for a given Stytch Session.


session_jwtstring

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


member_sessionobject

The Session object.


reset_sessionsboolean

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.

REQUEST

Node
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

200
{
  "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_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


certificate_idstring

The ID of the certificate that was deleted.

REQUEST

Node
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

200
{
  "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


organizationobject

The Organization object.


membershipobject

Information about the membership

Collapse


kindstring

Either active_member pending_member, invited_member, or eligible_to_join_by_email_domain


memberobject

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


detailsobject

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

OBJECT

Existing Member
{
  "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_tokenstring

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_tokenstring

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


session_jwtstring

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


Response fields


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


email_addressstring

The email address.


discovered_organizationarray

REQUEST

Node
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

200
{
	"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_minutesint

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


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_urlstring

The image URL of the Organization logo.


trusted_metadataobject

An arbitrary JSON object for storing application-specific data.


email_jit_provisioningstring

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_invitesstring

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_domainsarray[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_provisioningstring

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_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


member_idstring

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_tokenstring

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


session_jwtstring

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


member_sessionobject

The Session object.


memberobject

The Member object.


organizationobject

The Organization object.

REQUEST

Node
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

200
{
	"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_claimsmap<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_minutesint

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.


Response fields


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


member_idstring

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_tokenstring

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


session_jwtstring

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


member_sessionobject

The Session object.


memberobject

The Member object.


organizationobject

The Organization object.

REQUEST

Node
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

200
{
	"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_tokenstring

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_jwtstring

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_minutesint

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


Response fields


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


member_sessionobject

The Session object.


reset_sessionsboolean

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_tokenstring

A secret token for a given Stytch Session.


session_jwtstring

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


organization_idstring

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.


memberobject

The Member object.


organizationobject

The Organization object.

REQUEST

Node
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": "ZeEBbpki#LOaOBJv",
	  "session_duration_minutes": 30
	}'

RESPONSE

200
{
  "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_urlstring

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_urlstring

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_idstring

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.


localestring

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_minutesint

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


Response fields


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


member_idstring

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_idstring

Globally unique UUID that identifies a member's email

REQUEST

Node
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

200
{
  "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_tokenstring

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_jwtstring

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_minutesint

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


code_verifierstring

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


Response fields


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


member_idstring

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_sessionobject

The Session object.


session_tokenstring

A secret token for a given Stytch Session.


session_jwtstring

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


organization_idstring

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.


memberobject

The Member object.


organizationobject

The Organization object.

REQUEST

Node
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": "ZeEBbpki#LOaOBJv"
	}'

RESPONSE

200
{
  "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_tokenstring

A secret token for a given Stytch Session.


session_jwtstring

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


session_custom_claimsmap<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_minutesint

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.


Response fields


member_idstring

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.


memberobject

The Member object.


organizationobject

The Organization object.


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.

REQUEST

Node
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": "ZeEBbpki#LOaOBJv"
	}'

RESPONSE

200
{
    "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_tokenstring

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_jwtstring

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_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


member_sessionobject

The Session object.


memberobject

The Member object.

REQUEST

Node
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": "ZeEBbpki#LOaOBJv"
	  "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q"
	}'

RESPONSE

200
{
  "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_idstring

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.


memberobject

The Member object.


organizationobject

The Organization object.


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.

REQUEST

Node
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

200
{
    "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.

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.

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_addressstring

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_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


breach_detection_on_createboolean

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_passwordboolean

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


luds_feedbackobject

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

Collapse


luds_requirementsobject

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_digitboolean

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


has_lower_caseboolean

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


has_symbolboolean

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_caseboolean

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


missing_charactersinteger

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_complexityinteger

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_feedbackobject

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

Collapse


suggestionsarray

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


warningstring

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


scoreint

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_policystring

The strength policy type enforced, either zxcvbn or luds.


valid_passwordboolean

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

Node
curl --request POST \
	--url https://test.stytch.com/v1/b2b/passwords/strength_check \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	  "password": "ZeEBbpki#LOaOBJv"
	}'

RESPONSE

200
{
    "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_configobject

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

Collapse


saltstring

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


n_parameterint

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_parameterint

The r parameter, also known as the block size.


p_parameterint

The p parameter, also known as the parallelism factor.


key_lengthint

The key length, also known as the hash length.


argon_2_configobject

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

Collapse


saltstring

The salt value.


iteration_amountint

The iteration amount.


memoryint

The memory in kibibytes.


threadsint

The thread value, also known as the parallelism factor.


key_lengthint

The key length, also known as the hash length.


md_5_configobject

Optional parameters for MD-5 hash types.

Collapse


prepend_saltstring

The salt that should be prepended to the migrated password.


append_saltstring

The salt that should be appended to the migrated password.


sha_1_configobject

Optional parameters for SHA-1 hash types.

Collapse


prepend_saltstring

The salt that should be prepended to the migrated password.


append_saltstring

The salt that should be appended to the migrated password.


Response fields


member_idstring

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.


memberobject

The Member object.


organizationobject

The Organization object.


status_codeint

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.

REQUEST

Node
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

200
{
	"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

x509
-----BEGIN CERTIFICATE-----
MIIFIjCCAwoCCQC8brjOdUXVjTANBgkqhkiG9w0BAQsFADBTMQswCQYDVQQGEwJV
UzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzEX
MBUGA1UECgwOU3R5dGNoIEVYQU1QTEUwHhcNMjMwMjA5MjMwMjA0WhcNMjQwMjA5
MjMwMjA0WjBTMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQG
A1UEBwwNU2FuIEZyYW5jaXNjbzEXMBUGA1UECgwOU3R5dGNoIEVYQU1QTEUwggIi
MA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQDIRzEMPwjJgflImAYjSIfDMXCC
IBFhuhxY8/mnidMiMauGR+dEMP4Jlg8oOZSNMx8wfPH7aqRIM8dkj8BhJ3QUjQmA
XLSgYsBUSSMaELHCurPSdz+rHfUMfD/cag5GeyPM2KtBD3I/Du545SNeURwKaiB5
fwlfYblMGNFvB70KRpl/YkvBYL7knKTGe1K6NG56IyGhRguEpaksxBJ4RTXcNiWr
ENcrw88LUpJd+7cDTlLB+6N+hPWUS/91R5kbQw/GX23C6uUDxTtGimWvA+riV6OF
IjWf5oDWioZj9wUFXElw+mMmTYye/cIHtXlwia845dWD5Gn9o5hpXoPBzV9tNPce
FgUcaczFkyRpnPU6HwMNFkfGPYWyn8w1mW6DKCNwe6gG9PYejoTMsvIrsoB4e5mT
Y56ZbYZRCglzBOgQZZejxZfvhg5m027lNrAdr5keBF3QVZ6+LIoHbHIRhskYTg6N
oY+B7c2u8/wUux4r1CwjgE5I/NCFd4UsUIfyNNPiqMEHtiTKi1++/d8oFeGOrobK
9dCE9pQ7WFtHYgM0q7ygkXdfw4mspdhwjVKbPAjf6pGkMr/NvWKF23MZ4PU84NXn
nUZlUyPGXcB/IuGzIykBTLrvr9dyZXcF39LM9B2zoSknbvwv1yyvOjASEQeN9678
bBNHVCDFZ2F3xnyYtwIDAQABMA0GCSqGSIb3DQEBCwUAA4ICAQCSSpID/WriYgPD
vLRgETj6RWhKRaqga5endmFNE6/s5r7iJr/OPMNUUCqga1A2gtoP1jT4VX6qHMAL
zyiEoMYg3NosUZE78VqK25GLjwJ21w9KeocTNFFzir0uB+gDwnpY+er0OojwabMk
12AWFqRoSy6wHICYIcS6SCI0Sg7BWLV4bprSJ+zsV/pkDKJ3iwFcGNhTnOrPdpI6
zbyqG3MXnK5G2xVNbg/67oNQfd3Jis2Hlb7GYMnIEtU4j3Lw12yBvMIi0eJX0cim
/F7GJZKFEd5OuHF0rhHo36RYvrwxmjHu4pCqIO7vlW8NdSd86xL2mpRyQiqRcm3L
ZCAMdi+ykuOdW3FcKPDxB/GripTwzmtuK68hPwrl1QIsGl1toyXgLClRjete0EB2
bye4jWI0QHHJ/JA6xkD8O/3/q8aVcD0LgeBhEXYkQGZgbiVg1X9KXPdadKT+4GlD
9A7Yts1LcBX0kX91G2I++0JRMM0E5OwnG6MXtPJfmsLmPM3WkJHGf2PUY6k6xR+y
okXHOYlhkarZ3SKPVUWE5rpK4GtpYEOaLIrDAxRm2qm4NvDN7zuz51RhHh9DcP4v
QWz1JJ4v5Q63z2Mz8sIxDoWzxw9wl9wVq0u5QN2jP2cxGvdTG4rGTpZW5AT3LBWa
vgej5xjwiYfaoboTEHQE8iP+EPwtCA==
-----END CERTIFICATE-----

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_codeint

The HTTP status code of the error.


request_idstring

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.


error_typestring

The name of the error and its type.


error_messagestring

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

403
{
  "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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
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
Stytch Forum

Send us an email
support@stytch.com

Ask in Slack
Slack