Organizations overview

An Organization represents a tenant in your application - typically each of your business customers. Organizations contain members, authentication settings, and RBAC policies that are isolated from other organizations.

Organization management

Create an organization

Create a new organization using the Create Organization endpoint:

curl --request POST \
  --url https://test.stytch.com/v1/b2b/organizations \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "organization_name": "Acme Corporation",
    "organization_slug": "acme-corp",
    "email_allowed_domains": ["acme.com"]
  }'

Response:

{
  "status_code": 201,
  "organization": {
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "organization_name": "Acme Corporation",
    "organization_slug": "acme-corp",
    "email_allowed_domains": ["acme.com"],
    "email_jit_provisioning": "NOT_ALLOWED",
    "email_invites": "ALL_ALLOWED",
    "auth_methods": "ALL_ALLOWED",
    "allowed_auth_methods": [],
    "mfa_policy": "OPTIONAL"
  }
}

Update organization settings

Configure authentication methods, MFA policies, and other settings using the Update Organization endpoint:

curl --request PUT \
  --url https://test.stytch.com/v1/b2b/organizations/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931 \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "mfa_policy": "REQUIRED_FOR_ALL",
    "allowed_auth_methods": ["sso", "magic_link"],
    "email_jit_provisioning": "RESTRICTED",
    "email_allowed_domains": ["acme.com", "acmecorp.com"]
  }'

Key settings:

mfa_policy - Controls MFA requirements (OPTIONAL, REQUIRED_FOR_ALL)
auth_methods / allowed_auth_methods - Restrict which authentication methods members can use
email_jit_provisioning / email_allowed_domains - Configure automatic member provisioning by email domain
sso_jit_provisioning - Enable JIT provisioning for SSO connections

Search organizations

Find organizations by name, domain, or other criteria using the Search Organizations endpoint:

curl --request POST \
  --url https://test.stytch.com/v1/b2b/organizations/search \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "query": {
      "operator": "AND",
      "operands": [
        {
          "filter_name": "organization_name",
          "filter_value": ["Acme"]
        }
      ]
    }
  }'

Trusted metadata

Organizations support trusted_metadata for storing application-specific data:

curl --request PUT \
  --url https://test.stytch.com/v1/b2b/organizations/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931 \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "trusted_metadata": {
      "subscription_tier": "enterprise",
      "billing_id": "cus_123456",
      "feature_flags": {
        "advanced_analytics": true
      }
    }
  }'

Metadata constraints:

Maximum 20 top-level keys
Cannot exceed 4KB in size
Backend integrations can read and write
Frontend integrations can only read

Do not store sensitive information (credit card details, etc.) in metadata.

See Metadata Update Behavior for how updates are merged.

Learn more

Organization object

Complete organization object reference

Configure auth methods

Set up organization authentication policies

JIT provisioning

Automatic member provisioning guide

Organization management

Comprehensive organization management guide

​Organization management

​Trusted metadata

​Learn more

Organization object

Configure auth methods

JIT provisioning

Organization management

Organization management

Trusted metadata

Learn more