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.
Fields
OBJECT
{
"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"
}
],
"auth_methods": "ALL_ALLOWED",
"allowed_auth_methods": [],
"trusted_metadata": {
"address": {
"street": "1 Telegraph Hill Blvd",
"city": "San Francisco",
"state": "CA",
"zip_code": "94133"
},
"billing_tier": "free"
}
}
}Creates an Organization. An organization_name and a unique organization_slug are required.
By default, email_invites and sso_jit_provisioning 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.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/organizations \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"organization_name": "Example Org Inc.",
"organization_slug": "example-org"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"organization": {
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"organization_logo_url": "",
"organization_name": "Example Org Inc.",
"organization_slug": "example-org",
"email_allowed_domains": [],
"email_invites": "ALL_ALLOWED",
"email_jit_provisioning": "NOT_ALLOWED",
"sso_default_connection_id": null,
"sso_jit_provisioning": "NOT_ALLOWED",
"sso_jit_provisioning_allowed_connections": [],
"sso_active_connections": [],
"trusted_metadata": {},
"auth_methods": "ALL_ALLOWED",
"allowed_auth_methods": []
}
}Returns an Organization specified by organization_id.
Path parameters
REQUEST
curl --request GET \
--url https://test.stytch.com/v1/b2b/organizations/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"organization": {
"email_allowed_domains": [],
"email_invites": "ALL_ALLOWED",
"email_jit_provisioning": "NOT_ALLOWED",
"organization_id": "organization-test-staging-12345",
"organization_logo_url": "",
"organization_name": "Example Org Inc",
"organization_slug": "exampleorg",
"sso_default_connection_id": null,
"sso_jit_provisioning": "NOT_ALLOWED",
"sso_jit_provisioning_allowed_connections": [],
"sso_active_connections": [],
"trusted_metadata": {}
}
}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. test
*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
REQUEST
curl --request PUT \
--url https://test.stytch.com/v1/b2b/organizations/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"organization_name": "Example Org Inc.",
"email_jit_provisioning": "ALL_ALLOWED"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"organization": {
"email_allowed_domains": [],
"email_invites": "ALL_ALLOWED",
"email_jit_provisioning": "ALL_ALLOWED",
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"organization_logo_url": "",
"organization_name": "Example Org Inc.",
"organization_slug": "example-org",
"sso_default_connection_id": null,
"sso_jit_provisioning": "ALL_ALLOWED",
"sso_jit_provisioning_allowed_connections": [],
"sso_active_connections": [],
"trusted_metadata": {},
"auth_methods": "ALL_ALLOWED",
"allowed_auth_methods": []
}
}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.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/organizations/search \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"limit": 200,
"query": {
"operator": "OR",
"operands": [
{
"filter_name": "allowed_domains",
"filter_value": ["stytch.com"]
},
{
"filter_name": "organization_name_fuzzy",
"filter_value": "example org"
}
]
}
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"results_metadata": {
"next_cursor": null,
"total": 5
},
"organizations": [
...
]
}Deletes an Organization specified by organization_id. All Members of the Organization will also be deleted.
Path parameters
REQUEST
curl --request DELETE \
--url https://test.stytch.com/v1/b2b/organizations/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931"
}Fields
OBJECT
{
"member": {
"email_address": "sandbox@stytch.com",
"member_password_id": "member-password-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
"name": "Test Member",
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"status": "active",
"is_breakglass": false,
"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"]
}
}],
}
}Creates a Member. An organization_id and email_address are required.
Path parameters
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/organizations/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931/members \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email_address": "sandbox@stytch.com",
"name": "Carla Philips",
"trusted_metadata": {
"role": "admin"
},
"untrusted_metadata": {
"nickname": "Carly",
"preferred_locales": ["en", "es"]
}
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
"member": {...},
"organization": {...}
}Get a Member by member_id or email_address.
Path parameters
REQUEST
curl --request GET \
--url https://test.stytch.com/v1/b2b/organizations/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931/member?member_id=member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
"member": {...},
"organization": {...}
}Updates a Member specified by organization_id and member_id.
Path parameters
REQUEST
curl --request PUT \
--url https://test.stytch.com/v1/b2b/organizations/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931/members/member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"name": "Carla Philips",
"trusted_metadata": {
"role": "reader"
},
"untrusted_metadata": {
"nickname": "Carly",
"preferred_locales": ["en", "pt-br"]
}
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
"member": {...},
"organization": {...}
}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.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/organizations/members/search \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"organization_ids": ["organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931"],
"limit": 200,
"query": {
"operator": "OR",
"operands": [
{
"filter_name": "member_emails",
"filter_value": ["testmember@stytch.com"]
},
{
"filter_name": "status",
"filter_value": "active"
}
]
}
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"results_metadata": {
"next_cursor": null,
"total": 5
},
"members": [
...
]
"organizations": <
...
>
}Deletes a Member specified by organization_id and member_id.
Path parameters
REQUEST
curl --request DELETE \
--url https://test.stytch.com/v1/b2b/organizations/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931/members/member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f"
}Send 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.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/magic_links/email/login_or_signup \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"email_address": "sandbox@stytch.com"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
"member_created": true,
"member": {...},
"organization": {...}
}Send 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.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/magic_links/email/invite \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"email_address": "sandbox@stytch.com"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f"
"member": {...},
"organization": {...}
}Authenticate a Member with a Magic Link. This endpoint requires a Magic Link token that is not expired or previously used. Provide a value for session_duration_minutes to receive a Session. If the Member’s status is pending or invited, they will be updated to active.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/magic_links/authenticate \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"magic_links_token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4="
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"method_id": "member-email-test-1dd089b3-8904-47ef-b943-987968e549d4",
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"reset_sessions": false,
"session_jwt": "example_jwt",
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
"member_session": {...},
"member": {...},
"organization": {...}
}Send a discovery magic link to an email address.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/magic_links/email/discovery/send \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"email_address": "sandbox@stytch.com"
}'RESPONSE
{
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"status_code": 200
}Authenticates the discovery Magic Link token and exchanges it for an Intermediate Session Token. Intermediate Session Tokens can be used for various Discovery login flows and are valid for 10 minutes.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/magic_links/discovery/authenticate \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"discovery_magic_links_token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4="
}'RESPONSE
{
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"status_code": 200,
"intermediate_session_token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
"email_address": "sandbox@stytch.com",
"discovered_organizations": [{...}, {...}]
}OAuth is a popular authentication framework that delegates authentication to an external identity provider (often shortened to IdP) like Google or Microsoft. A user relies on their membership from that provider to sign in instead of creating another password, and developers can enrich their users' experiences with the information shared by the providers. While OAuth has many benefits, developers need to understand the OAuth framework well to implement it securely. Stytch's OAuth product simplifies the process by abstracting the implementation details of OAuth for developers. The steps for an OAuth flow are simple:
A client-side endpoint (which can only be queried from the user's browser) that starts the Google OAuth flow. This endpoint generates the Google OAuth URL with all required fields and redirects the user to that URL. The user authenticates with Google before getting redirected back to Stytch. After verifying the request, Stytch redirects the user back to the login_redirect_url or signup_redirect_url URL provided.
One of organization_id or organization_slug is required to specify which organization the user is trying to access. If the organization that the user is trying to access is not yet known, use the Google OAuth Discovery endpoint instead.
By default our Google OAuth integration requests the open_id, email, and profile scopes. You may add any additional Google API scopes (see here for a complete list) as a space separated list in the custom_scopes query parameter.
Once the user successfully authenticates with Google, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth Token to complete authentication.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/b2b/public/oauth/google/start?public_token=PUBLIC_TOKEN&organization_id=organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://accounts.google.com/o/oauth2/v2/auth/identifier?client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=openid%20email%20profile&access_type=offline&state=example-state",
}A client-side endpoint (which can only be queried from the user's browser) that starts the Microsoft OAuth flow. This endpoint generates the Microsoft OAuth URL with all required fields and redirects the user to that URL. The user authenticates with Microsoft Account before getting redirected back to Stytch. After verifying the request, Stytch redirects the user back to the login_redirect_url or signup_redirect_url URL provided.
One of organization_id or organization_slug is required to specify which organization the user is trying to access. If the organization that the user is trying to access is not yet known, use the Microsoft OAuth Discovery endpoint instead.
NOTE: The Stytch B2B product limits access to only verified Azure Active Directory accounts. Personal accounts, including personal Xbox Live, Skype, or Outlook accounts, are not allowed. Accounts managed by Azure Active Directory B2C are not allowed. By default, Stytch will deduplicate users by treating their UserPrincipalName as an email address. Reach out to support@stytch.com if you would like finer control over this behavior.
By default our Microsoft OAuth integration includes open_id, email, User.Read, and profile scopes. You may add any additional Microsoft API scopes (see here for a complete list) as a space separated list in the custom_scopes query parameter of /oauth/microsoft/start.
Once the user successfully authenticates with Microsoft, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth Token to complete authentication.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/b2b/public/oauth/microsoft/start?public_token=PUBLIC_TOKEN&organization_id=organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=openid+email+profile&state=example-state",
}Authenticate a Member given a token. This endpoint verifies that the member completed the OAuth flow by verifying that the token is valid and hasn't expired.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/oauth/authenticate \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"oauth_token": "hdPVZHHX0UoRa7hJTuuPHi1vlddffSnoweRbVFf5-H8g",
"session_duration_minutes": 60
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"session_jwt": "example_jwt",
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
"member_session": {...},
"member": {...},
"organization": {...},
"provider_values": {
"access_token": "example-access-token",
"refresh_token": "example-refresh-token",
"id_token": "example-id-token",
"scopes": ["example scope"]
},
}A client-side endpoint (can only be queried from the user's browser) that starts the Google OAuth flow. This endpoint generates the Google OAuth URL with all required fields and redirects the user to that URL. The user authenticates with Google before getting redirected back to Stytch. After verifying the request, Stytch redirects the user back to the discovery_redirect_url provided.
By default our Google OAuth integration requests the open_id, email, and profile scopes. You may add any additional Google API scopes (see here for a complete list) as a space separated list in the custom_scopes query parameter.
Once the user successfully authenticates with Google, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate Discovery OAuth to exchange it for an Intermediate Session Token. Intermediate Session Tokens can be used for various Discovery login flows and are valid for 10 minutes.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/b2b/public/discovery/oauth/google/start?public_token=PUBLIC_TOKEN'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://accounts.google.com/o/oauth2/v2/auth/identifier?client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=openid%20email%20profile&access_type=offline&state=example-state",
}A client-side endpoint (can only be queried from the user's browser) that starts the Microsoft OAuth flow. This endpoint generates the Microsoft OAuth URL with all required fields and redirects the user to that URL. The user authenticates with Microsoft before getting redirected back to Stytch. After verifying the request, Stytch redirects the user back to the discovery_redirect_url provided.
By default our Microsoft OAuth integration includes open_id, email, User.Read, and profile scopes. You may add any additional Microsoft API scopes (see here for a complete list) as a space separated list in the custom_scopes query parameter of /oauth/microsoft/start.
Once the user successfully authenticates with Microsoft, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate Discovery OAuth to exchange it for an Intermediate Session Token. Intermediate Session Tokens can be used for various Discovery login flows and are valid for 10 minutes.
REQUEST
curl --request GET \
--url 'https://test.stytch.com/v1/b2b/public/discovery/oauth/microsoft/start?public_token=PUBLIC_TOKEN'RESPONSE
{
"status_code": 302,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"redirect_url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?access_type=offline&client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&scope=openid+email+profile+User.Read&state=example-state",
}Authenticates the discovery OAuth token and exchanges it for an Intermediate Session Token. Intermediate Session Tokens can be used for various Discovery login flows and are valid for 10 minutes.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/oauth/discovery/authenticate \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"discovery_oauth_token": "hdPVZHHX0UoRa7hJTuuPHi1vlddffSnoweRbVFf5-H8g",
"session_duration_minutes": 60
}'RESPONSE
{
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"status_code": 200,
"intermediate_session_token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
"email_address": "sandbox@stytch.com",
"discovered_organizations": [{...}, {...}]
}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. If the session_duration_minutes parameter is not specified, a Stytch session will be created with a 60 minute duration. Look for session_token and session_jwt in the response.
Fields
OBJECT
{
"member_session": {
"member_session_id": "session-test-fe6c042b-6286-479f-8a4f-b046a6c46509",
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
"started_at": "2023-01-09T07:41:52Z",
"last_accessed_at": "2023-01-09T07:41:52Z",
"expires_at": "2021-08-10T07:41:52Z",
"authentication_factors": [
{
"delivery_method": "email",
"email_factor": {
"email_address": "sandbox@stytch.com",
"email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
},
"last_authenticated_at": "2023-01-09T07:41:52Z",
"type": "magic_link"
}
],
"custom_claims": {
"claim1": "value1",
"claim2": "value2",
},
}
}Get the JSON Web Key Set (JWKS) for a project.
Path parameters
REQUEST
curl --request GET \
--url https://test.stytch.com/v1/sessions/jwks/PROJECT_IDRESPONSE
{
"status_code": 200,
"keys": [
{
"alg": "RS256",
"e": "example-e",
"key_ops": ["verify"],
"kid": "example-key-id",
"kty": "RSA",
"n": "example-n",
"use": "sig",
"x5c": ["example-x5c"],
"x5tS256": "example-x5tS256",
},
],
}Retrieves all active Sessions for a Member.
REQUEST
curl --request GET \
--url https://test.stytch.com/v1/b2b/sessions?organization_id=organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931&member_id=member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"member_sessions": [...]
}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.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/sessions/authenticate \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"member_session": {...},
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
"session_jwt": "",
"member": {...},
"organization": {...}
}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.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/sessions/exchange \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q"
}'RESPONSE
{
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"status_code": 200,
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
"session_jwt": "example_jwt",
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
"member_session": {...},
"member": {...},
"organization": {...}
}Revoke 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.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/sessions/revoke \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141"
}Single-Sign On (SSO) refers to the ability for a user to use a single identity to authenticate and gain access to multiple apps and service. In the case of B2B, it generally refers for the ability to use a workplace identity managed by their company. Read our blog post for more information about SSO.
Stytch supports the following SSO protocols:
In order to set up SSO for your app, you'll need to take the following steps:
Fields
OBJECT
{
"connection": {
"acs_url": "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
"attribute_mapping": {
"email": "email",
"full_name": "name"
},
"audience_uri": "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
"connection_id": "saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
"display_name": "Example SAML Connection",
"idp_entity_id": "https://idp.example.com/51861cbc-d3b9-428b-9761-227f5fb12be9",
"idp_sso_url": "https://idp.example.com/51861cbc-d3b9-428b-9761-227f5fb12be9/sso/saml",
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"signing_certificates": [
{
"certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE",
"created_at": "2023-01-01T00:00:00Z",
"expires_at": "2033-01-01T00:00:00Z",
"id": "",
"issuer": "Stytch"
}
],
"status": "active",
"verification_certificates": [
{
"certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE",
"created_at": "2023-01-01T00:00:00Z",
"expires_at": "2033-01-01T00:00:00Z",
"id": "saml-verification-key-test-5ccbc642-9373-42b8-928f-c1646c868701",
"issuer": ""
}
]
},
}Fields
OBJECT
{
"connection": {
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"connection_id": "oidc-connection-test-b6c714c2-7413-4b92-a0f1-97aa1085aeff",
"display_name": "Example OIDC Connection",
"redirect_url": "https://test.stytch.com/v1/b2b/sso/callback/oidc-connection-test-b6c714c2-7413-4b92-a0f1-97aa1085aeff"
"status": "active",
"issuer": "https://idp.example.com/",
"client_id": "s6BhdRkqt3",
"client_secret": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
"authorization_url": "https://idp.example.com/authorize"
"token_url": "https://idp.example.com/oauth2/token"
"userinfo_url": "https://idp.example.com/userinfo"
"jwks_url": "https://idp.example.com/oauth2/jwks"
}
}Create a new SAML Connection.
Path parameters
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/sso/saml/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"display_name": "Example SAML Connection"
}'RESPONSE
{
"connection": {
"acs_url": "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
"attribute_mapping": {
"email": "email",
"full_name": "name",
},
"audience_uri": "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
"connection_id": "saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
"display_name": "",
"idp": "",
"idp_entity_id": "",
"idp_sso_url": "",
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"signing_certificates": [
{
"certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE",
"id": "",
"created_at": "2023-01-01T00:00:00Z",
"expires_at": "2033-01-01T00:00:00Z",
"issuer": "Stytch"
}
],
"status": "pending",
"verification_certificates": []
},
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"status_code": 200
}Updates an existing SAML connection.
Note that a newly created connection will not become active until all of the following are provided:
Path parameters
REQUEST
curl --request PUT \
--url https://test.stytch.com/v1/b2b/sso/saml/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931/connections/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"entity_id": "https://idp.example.com/51861cbc-d3b9-428b-9761-227f5fb12be9",
"display_name": "Example SAML Connection",
"attribute_mapping": {
"email": "NameID",
"first_name": "firstName",
"last_name": "lastName"
},
"idp_sso_url": "https://idp.example.com/51861cbc-d3b9-428b-9761-227f5fb12be9/sso/saml",
"x509_certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE"
}'RESPONSE
{
"connection": {
"acs_url": "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
"attribute_mapping": {
"email": "email",
"full_name": "name"
},
"audience_uri": "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
"connection_id": "saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
"display_name": "Example SAML Connection",
"idp_entity_id": "https://idp.example.com/51861cbc-d3b9-428b-9761-227f5fb12be9",
"idp_sso_url": "https://idp.example.com/51861cbc-d3b9-428b-9761-227f5fb12be9/sso/saml",
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"signing_certificates": [
{
"certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE",
"created_at": "2023-01-01T00:00:00Z",
"expires_at": "2033-01-01T00:00:00Z",
"id": "",
"issuer": "Stytch"
}
],
"status": "active",
"verification_certificates": [
{
"certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE",
"created_at": "2023-01-01T00:00:00Z",
"expires_at": "2033-01-01T00:00:00Z",
"id": "saml-verification-key-test-5ccbc642-9373-42b8-928f-c1646c868701",
"issuer": ""
}
]
},
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"status_code": 200
}Create a new OIDC Connection.
Path parameters
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/sso/oidc/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"display_name": "Example OIDC Connection"
}'RESPONSE
{
"connection": {
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"connection_id": "oidc-connection-test-b6c714c2-7413-4b92-a0f1-97aa1085aeff",
"display_name": "Example OIDC Connection",
"redirect_url": "https://test.stytch.com/v1/b2b/sso/callback/oidc-connection-test-b6c714c2-7413-4b92-a0f1-97aa1085aeff"
"status": "active",
"issuer": "https://idp.example.com/",
"client_id": "s6BhdRkqt3",
"client_secret": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
"authorization_url": "https://idp.example.com/authorize"
"token_url": "https://idp.example.com/oauth2/token"
"userinfo_url": "https://idp.example.com/userinfo"
"jwks_url": "https://idp.example.com/oauth2/jwks"
},
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"status_code": 200
}Updates an existing OIDC connection.
When the value of issuer changes, Stytch will attempt to retrieve the OpenID Provider Metadata document found at ${issuer}/.well-known/openid-configuration. If the metadata document can be retrieved successfully, Stytch will use it to infer the values of authorization_url, token_url, jwks_url, and userinfo_url. The client_id and client_secret values cannot be inferred from the metadata document, and must be passed in explicitly.
If the metadata document cannot be retrieved, Stytch will still update the connection using values from the request body.
If the metadata document can be retrieved, and values are passed in the request body, the explicit values passed in from the request body will take precedence over the values inferred from the metadata document.
Note that a newly created connection will not become active until all of the following fields are provided:
Path parameters
REQUEST
curl --request PUT \
--url https://test.stytch.com/v1/b2b/sso/oidc/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931/connections/oidc-connection-test-b6c714c2-7413-4b92-a0f1-97aa1085aeff \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"display_name": "Example SAML Connection",
"issuer": "https://idp.example.com/",
"client_id": "s6BhdRkqt3",
"client_secret": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
"authorization_url": "https://idp.example.com/authorize"
}'RESPONSE
{
"connection": {
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"connection_id": "oidc-connection-test-b6c714c2-7413-4b92-a0f1-97aa1085aeff",
"display_name": "Example OIDC Connection",
"redirect_url": "https://test.stytch.com/v1/b2b/sso/callback/oidc-connection-test-b6c714c2-7413-4b92-a0f1-97aa1085aeff"
"status": "active",
"issuer": "https://idp.example.com/",
"client_id": "s6BhdRkqt3",
"client_secret": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
"authorization_url": "https://idp.example.com/authorize"
"token_url": "https://idp.example.com/oauth2/token"
"userinfo_url": "https://idp.example.com/userinfo"
"jwks_url": "https://idp.example.com/oauth2/jwks"
},
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"status_code": 200
}Get all SSO Connections owned by the organization.
Path parameters
REQUEST
curl --request GET \
--url https://test.stytch.com/v1/b2b/sso/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json'RESPONSE
{
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"status_code": 200,
"saml_connections": [{...}, {...}],
"oidc_connections": [{...}, {...}]
}Delete an existing SSO connection.
REQUEST
curl --request DELETE \
--url https://test.stytch.com/v1/b2b/sso/{organization_id}/connections/{connection_id} \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json'RESPONSE
{
"connection_id": "saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"status_code": 200
}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.
REQUEST
curl --url https://test.stytch.com/v1/public/sso/start?connection_id=saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9&public_token=PUBLIC_TOKENRESPONSE
{
"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 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.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/sso/authenticate \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4="
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"member": {...},
"organization": {...},
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
"session_jwt": "eyJ...",
"member_session": {...},
}Delete 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
REQUEST
curl --request DELETE \
--url https://test.stytch.com/v1/b2b/sso/saml/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931/connections/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9/verification_certificates/saml-verification-key-test-5ccbc642-9373-42b8-928f-c1646c868701 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"certificate_id": "saml-verification-key-test-5ccbc642-9373-42b8-928f-c1646c868701",
}The Discovery product lets End Users 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 in advance. This is done via a Discovery Magic Link flow. After an End User is authenticated, an Intermediate Session is returned along with a list of associated Organizations.
The End User 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.
Fields
OBJECT
{
"organization": {
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"organization_name": "Example Org Inc.",
"organization_slug": "example-org",
...
},
"membership": {
"type": "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
},
"member_authenticated": true
}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.
This operation does not consume the Intermediate Session or Session Token passed in.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/discovery/organizations \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"intermediate_session_token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4="
}'RESPONSE
{
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"status_code": 200,
"email_address": "sandbox@stytch.com",
"discovered_organizations": [{...}, {...}]
}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 operation consumes the Intermediate Session.
This endpoint can also be used to start an initial session for the newly created member and organization.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/discovery/organizations \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"intermediate_session_token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
"session_duration_minutes": 60,
"organization_name": "Example Org Inc.",
"organization_slug": "example-org"
}'RESPONSE
{
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"status_code": 200,
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
"session_jwt": "eyJ...",
"member_session": {...},
"member": {...},
"organization": {...}
}Exchange an Intermediate Session for a fully realized Member Session in a desired Organization. This operation consumes the Intermediate Session.
This endpoint can be used to accept invites and create new members via domain matching.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/discovery/intermediate_sessions/exchange \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"intermediate_session_token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"session_duration_minutes": 60
}'RESPONSE
{
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"status_code": 200,
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
"session_jwt": "eyJ...",
"member_session": {...},
"member": {...},
"organization": {...}
}Stytch Passwords support creating, storing, and authenticating password-based Members, as well as 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 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:
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/passwords/authenticate \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"email_address": "sandbox@stytch.com",
"password": "N4#4G+@3(q${examplePassword}COti",
"session_duration_minutes": 30
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"session_jwt": "example_jwt",
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
"member_session": {...},
"member": {...},
"organization": {...}
}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.
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.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/passwords/email/reset/start \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"email_address": "sandbox@stytch.com",
"reset_password_redirect_url": "https://someexample.com",
"login_redirect_url": "https://someexample.com",
"reset_password_expiration_minutes": 10
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
"member_email_id": "member-email-test-1dd089b3-8904-47ef-b943-987968e549d4",
"member": {...}
}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.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/passwords/email/reset \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"password_reset_token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
"password": "N4#4G+@3(q${examplePassword}COti"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
"member_email_id": "member-email-test-1dd089b3-8904-47ef-b943-987968e549d4",
"member": {...}
}Reset the member’s password using their existing 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.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/passwords/existing_password/reset \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"email_address": "sandbox@stytch.com",
"existing_password": "old_password",
"new_password": "N4#4G+@3(q${examplePassword}COti"
}'RESPONSE
{
"member": {...},
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
"member_session": {...},
"organization": {...}
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"session_jwt": "example_jwt",
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
"status_code": 200
}Reset the Member's password using their existing session. The endpoint will error if the session does not an authentication factor that has been issued within the last 5 minutes.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/passwords/session/reset \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"password": "N4#4G+@3(q${examplePassword}COti"
"session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q"
}'RESPONSE
{
"status_code": 200,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
"member_session": {...},
"member": {...},
}Delete a Member's password.
Path parameters
REQUEST
curl --request DELETE \
--url https://test.stytch.com/v1/b2b/organizations/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931/members/passwords/member-password-test-51861cbc-d3b9-428b-9761-227f5fb12be9 \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json'RESPONSE
{
"member": {...},
"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
"organization": {...}
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"status_code": 200
}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.
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.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/passwords/strength_check \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"password": "N4#4G+@3(q${examplePassword}COti"
}'RESPONSE
{
"breach_detection_on_create": true,
"breached_password": false,
"luds_feedback": {},
"request_id": "request-id-test-f3aca0eb-e38f-4e0a-b5cc-e6e52ad88c71",
"score": 0,
"status_code": 200,
"strength_policy": "zxcvbn",
"valid_password": false,
"zxcvbn_feedback": {
"suggestions": [
"Add another word or two. Uncommon words are better."
],
"warning": ""
}
}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.
REQUEST
curl --request POST \
--url https://test.stytch.com/v1/b2b/passwords/migrate \
-u 'PROJECT_ID:SECRET' \
-H 'Content-Type: application/json' \
-d '{
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"email_address": "sandbox@stytch.com",
"hash": "$2b$04$oa70000TFDu3icElr2qML7Le",
"hash_type": "bcrypt"
}'RESPONSE
{
"connection": {
"acs_url": "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
"attribute_mapping": {
"email": "email",
"full_name": "name",
},
"audience_uri": "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
"connection_id": "saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
"display_name": "",
"idp": "",
"idp_entity_id": "",
"idp_sso_url": "",
"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
"signing_certificates": [
{
"certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE",
"id": "",
"created_at": "2023-01-01T00:00:00Z",
"expires_at": "2033-01-01T00:00:00Z",
"issuer": "Stytch"
}
],
"status": "pending",
"verification_certificates": []
},
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"status_code": 200
}Learn more about Stytch concepts, data models, and general B2B API concerns.
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.
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:
Auth settings for Single Sign On:
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
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.
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 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.
Stytch Members may contain metadata - arbitrary JSON objects for recording application-specific information.
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 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.
Initial:
{
"trusted_metadata": {
"key1": "value1"
}
}
Update:
{
"trusted_metadata": {
"key2": "value2"
}
}
Result:
{
"trusted_metadata": {
"key1": "value1",
"key2": "value2"
}
}
Initial:
{
"untrusted_metadata": {
"key1": "value1"
}
}
Update:
{
"untrusted_metadata": {
"key1": "value2"
}
}
Result:
{
"untrusted_metadata": {
"key1": "value2"
}
}
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"
}
}
Initial:
{
"untrusted_metadata": {
"key1": [{"deep": "value1"}],
"other_key": "other_value"
}
}
Update:
{
"untrusted_metadata": {
"key1": null
}
}
Result:
{
"untrusted_metadata": {
"other_key": "other_value"
}
}
Initial:
{
"trusted_metadata": {
"key1": [{"deep": "value1"}],
"other_key": "other_value"
}
}
Update:
{
"trusted_metadata": {
"key1": null,
"other_key": null
}
}
Result:
{
"trusted_metadata": {}
}
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, invite, discovery, or password reset), 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.
By default, all redirect URLs are set to http://localhost:3000 for the Test environment.
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 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
-----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-----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:
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.
OBJECT
{
"status_code": 403,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "use_https",
"error_message": "Please use https instead of http.",
"error_url": "https://stytch.com/docs/b2b/api/errors/403/use_https"
}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"
}Allowed auth methods must be set for 'RESTRICTED' auth methods
Error
{
"status_code": 400,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "allowed_auth_methods_required_for_restricted",
"error_message": "Allowed auth methods must be set for 'RESTRICTED' auth methods",
"error_url": "https://stytch.com/docs/b2b/api/errors/400/allowed_auth_methods_required_for_restricted"
}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"
}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"
}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"
}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 5,000 monthly active users are free every month, but collecting this information helps us prevent abuse of the platform. Please go to 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": "ou 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 5,000 monthly active users are free every month, but collecting this information helps us prevent abuse of the platform. Please go to https://stytch.com/settings/billing to provide billing information.",
"error_url": "https://stytch.com/docs/b2b/api/errors/400/billing_not_verified"
}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 5,000 monthly active users are free every month, but collecting this information helps us prevent abuse of the platform. Please go to 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 5,000 monthly active users are free every month, 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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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_oidc_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_oidc_response"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}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"
}