Managing Organization settings

Organizations have configurable settings for access control and regulating the authentication and provisioning of Members. Each Organization can have its own unique combination of settings to solve for different authentication requirements.

In this guide, you'll learn how to manage an Organization's settings. By the end, you'll have:

Updated an Organization's settings to control allowed auth methods.
Updated an Organization's settings to control Email Magic Links.
Updated an Organization's settings to control Single Sign On.
Updated an Organization's settings to control Multi-Factor Authentication.

Before you start

In order to complete this guide, you'll need the following:

A Stytch B2B project. If you don't have one already, in the Dashboard, click on your existing project name in the top left corner of the Dashboard, click Create a new project, and then select B2B Authentication.
The project Test environment's project_id and secret from the API keys section. You'll need to pass these values into the Authorization request header for every Stytch API call.
An Organization with at least one SSO connection. Check out this guide to set up an Okta SAML Connection. Your Organization object should look like this:

{
  "organization_id": "organization-test-f777e618-14d0-4fc1-bcc9-1b2c1e8d6d57",
  "organization_name": "Example org",
  "organization_logo_url": "",
  "organization_slug": "example-org",
  "trusted_metadata": {},
  "sso_default_connection_id": "saml-connection-test-7111f7b1-9896-4ce3-a658-9e0707fc5192",
  "sso_jit_provisioning": "ALL_ALLOWED",
  "sso_jit_provisioning_allowed_connections": [],
  "sso_active_connections": [
    {
      "connection_id": "saml-connection-test-7111f7b1-9896-4ce3-a658-9e0707fc5192",
      "display_name": "Okta test 2"
    }
  ],
  "email_allowed_domains": [],
  "email_jit_provisioning": "NOT_ALLOWED",
  "email_invites": "ALL_ALLOWED",
  "auth_methods": "ALL_ALLOWED",
  "allowed_auth_methods": [],
  "mfa_policy": "OPTIONAL",
}

Step 1: Update an Organization to restrict the allowed auth methods

On the Organization object, two fields control which auth methods are allowed to be used for authentication:

auth_methods: a string value that can be set to either ALL_ALLOWED or RESTRICTED.
allowed_auth_methods: an array of string values. The list's accepted values are sso, magic_link, and password – the names of specific auth methods.

These two fields have interdependent behavior.

When auth_methods is set to ALL_ALLOWED, an Organization accepts all available auth methods (Email Magic Links, Single Sign On, Passwords) as a valid way for Members to authenticate. As a result, the allowed_auth_methods is effectively disregarded.

When auth_methods is set to RESTRICTED, the Organization only accepts auth methods that comply with the allowed_auth_methods list as a valid way for Members to authenticate.

Call the Update Organization endpoint and pass in the following params.

curl --request PUT \
	--url https://test.stytch.com/v1/b2b/organizations/{ORGANIZATION_ID} \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"auth_methods": "RESTRICTED",
		"allowed_auth_methods": ["magic_link"]
	}'

After a successful API call:

The Organization will only accept Email Magic Links as a valid way to authenticate.
Members who attempt to authenticate into the Organization with the active SSO connection will encounter an error.

Step 2: Update an Organization to control EML auth behavior

On the Organization object, three fields control Email Magic Links:

email_invites: a string value that accepts ALL_ALLOWED, RESTRICTED, or NOT_ALLOWED.
email_jit_provisioning: a string value that accepts RESTRICTED or NOT_ALLOWED.
email_allowed_domains: an array of string values with domain name string patterns like stytch.com.

These three fields have interdependent behavior.

When email_invites is set to ALL_ALLOWED, an invite Email Magic Link can be sent to any email address for a new Member to join.

When either email_invites or email_jit_provisioning is set to RESTRICTED, the email address of the end user who is accepting an invite or signing up must comply with the email_allowed_domains list.

Call the Update Organization endpoint and pass in the following params.

curl --request PUT \
	--url https://test.stytch.com/v1/b2b/organizations/{ORGANIZATION_ID} \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"email_invites": "RESTRICTED",
        "email_jit_provisioning": "RESTRICTED",
		"email_allowed_domains": ["stytch.com"]
	}'

After a successful API call:

The Organization can only send EML invites to email accounts that match the domain stytch.com.
End users who sign up, for example with the Send Login Or Signup Email endpoint, will only be provisioned as Members if they have an email address that matches the domain stytch.com.

Step 3: Update an Organization to control SSO auth behavior

On the Organization object, three fields control Single Sign On:

sso_default_connection_id: a string value that accepts a connection_id.
sso_jit_provisioning: a string value that accepts ALL_ALLOWED, RESTRICTED, or NOT_ALLOWED.
sso_jit_provisioning_allowed_connections: an array of string values that accept multiple connection_ids.

These three fields have interdependent behavior.

When sso_default_connection_id is populated, the Organization will use the specified SSO connection as the default for SSO login flows when there are multiple active connections.

When sso_jit_provisioning is set to ALL_ALLOWED, the sso_jit_provisioning_allowed_connections is effectively disregarded. End users can use any of the active connections to sign up and be provisioned as Members.

When sso_jit_provisioning is set to RESTRICTED, end users can only sign up if they authenticate with one of the sso_jit_provisioning_allowed_connections.

Call the Update Organization endpoint and pass in the following params.

curl --request PUT \
	--url https://test.stytch.com/v1/b2b/organizations/{ORGANIZATION_ID} \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
        "auth_methods": "RESTRICTED",
		"allowed_auth_methods": ["magic_link", "sso"],
		"sso_default_connection_id": "{connection_id}",
        "sso_jit_provisioning": "RESTRICTED",
		"sso_jit_provisioning_allowed_connections": ["{connection_id}"]
	}'

After a successful API call:

The Organization will accept both Email Magic Links and Single Sign On as valid ways to authenticate.
Members who attempt to authenticate into the Organization with Passwords will encounter an error.
When calling the Start SSO Authentcate endpoint, the sso_default_connection_id will be used if a connection_id is not provided.
End users who sign up will only be provisioned as Members if their SSO connection complies with the sso_jit_provisioning_allowed_connections list.

Step 4: Update an Organization to control Multi-Factor Authentication

On the Organization object, one primary field controls Multi-Factor Authentication: mfa_policy, a string value that can be set to either OPTIONAL or REQUIRED_FOR_ALL.

When mfa_policy is set to REQUIRED_FOR_ALL, all Members will be required to complete the MFA flow in order to log in.

When set to OPTIONAL, only Members who have their mfa_enrolled status set to true must complete the MFA flow. Check out this guide to learn how individual Members can opt to enroll in MFA.

Call the Update Organization endpoint and pass in the following parameters.

curl --request PUT \
	--url https://test.stytch.com/v1/b2b/organizations/{ORGANIZATION_ID} \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
        "mfa_policy": "REQUIRED_FOR_ALL"
	}'

After a successful API call:

The Organization will require all Members to complete the MFA flow in order to mint an authenticated Session.
Members will receive an intermediate_session_token and a member_authenticated flag set to false in the response after authenticating with a primary factor.
Members will receive a fully minted Session only after authenticating with a second factor and passing in the previous intermediate_session_token as a parameter, completing the MFA flow.

What's next

Complete a guide for signing up or logging in Members using EML, Discovery EML or SAML with Okta.

Clone our B2B Next.js example app for helpful templates that can get you started quickly. Also, check out our interactive B2B demo app to see the app in action.