Skip to main content
POST
/
v1
/
b2b
/
organizations
/
{organization_id}
/
members
/
{member_id}
/
start_email_update
C#
// POST /v1/b2b/organizations/{organization_id}/members/{member_id}/start_email_update
const stytch = require('stytch');

const client = new stytch.B2BClient({
  project_id: '${projectId}',
  secret: '${secret}',
});

const params = {
  organization_id: "${organizationId}",
  member_id: "${memberId}",
  email_address: "${email}",
};

const options = {
  authorization: {
    session_token: '${sessionToken}',
  },
};

client.Organizations.Members.StartEmailUpdate(params, options)
  .then(resp => { console.log(resp) })
  .catch(err => { console.log(err) });
{
  "request_id": "<string>",
  "member_id": "<string>",
  "member": {
    "organization_id": "<string>",
    "member_id": "<string>",
    "email_address": "<string>",
    "status": "<string>",
    "name": "<string>",
    "sso_registrations": [
      {
        "connection_id": "<string>",
        "external_id": "<string>",
        "registration_id": "<string>",
        "sso_attributes": {}
      }
    ],
    "is_breakglass": true,
    "member_password_id": "<string>",
    "oauth_registrations": [
      {
        "provider_type": "<string>",
        "provider_subject": "<string>",
        "member_oauth_registration_id": "<string>",
        "profile_picture_url": "<string>",
        "locale": "<string>"
      }
    ],
    "email_address_verified": true,
    "mfa_phone_number_verified": true,
    "is_admin": true,
    "totp_registration_id": "<string>",
    "retired_email_addresses": [
      {
        "email_id": "<string>",
        "email_address": "<string>"
      }
    ],
    "is_locked": true,
    "mfa_enrolled": true,
    "mfa_phone_number": "<string>",
    "default_mfa_method": "<string>",
    "roles": [
      {
        "role_id": "<string>",
        "sources": [
          {
            "type": "<string>",
            "details": {}
          }
        ]
      }
    ],
    "trusted_metadata": {},
    "untrusted_metadata": {},
    "created_at": "<string>",
    "updated_at": "<string>",
    "scim_registration": {
      "connection_id": "<string>",
      "registration_id": "<string>",
      "external_id": "<string>",
      "scim_attributes": {
        "user_name": "<string>",
        "id": "<string>",
        "external_id": "<string>",
        "active": true,
        "groups": [
          {
            "value": "<string>",
            "display": "<string>"
          }
        ],
        "display_name": "<string>",
        "nick_name": "<string>",
        "profile_url": "<string>",
        "user_type": "<string>",
        "title": "<string>",
        "preferred_language": "<string>",
        "locale": "<string>",
        "timezone": "<string>",
        "emails": [
          {
            "value": "<string>",
            "type": "<string>",
            "primary": true
          }
        ],
        "phone_numbers": [
          {
            "value": "<string>",
            "type": "<string>",
            "primary": true
          }
        ],
        "addresses": [
          {
            "formatted": "<string>",
            "street_address": "<string>",
            "locality": "<string>",
            "region": "<string>",
            "postal_code": "<string>",
            "country": "<string>",
            "type": "<string>",
            "primary": true
          }
        ],
        "ims": [
          {
            "value": "<string>",
            "type": "<string>",
            "primary": true
          }
        ],
        "photos": [
          {
            "value": "<string>",
            "type": "<string>",
            "primary": true
          }
        ],
        "entitlements": [
          {
            "value": "<string>",
            "type": "<string>",
            "primary": true
          }
        ],
        "roles": [
          {
            "value": "<string>",
            "type": "<string>",
            "primary": true
          }
        ],
        "x509certificates": [
          {
            "value": "<string>",
            "type": "<string>",
            "primary": true
          }
        ],
        "name": {
          "formatted": "<string>",
          "family_name": "<string>",
          "given_name": "<string>",
          "middle_name": "<string>",
          "honorific_prefix": "<string>",
          "honorific_suffix": "<string>"
        },
        "enterprise_extension": {
          "employee_number": "<string>",
          "cost_center": "<string>",
          "division": "<string>",
          "department": "<string>",
          "organization": "<string>",
          "manager": {
            "value": "<string>",
            "ref": "<string>",
            "display_name": "<string>"
          }
        }
      }
    },
    "external_id": "<string>",
    "lock_created_at": "<string>",
    "lock_expires_at": "<string>"
  },
  "organization": {
    "organization_id": "<string>",
    "organization_name": "<string>",
    "organization_logo_url": "<string>",
    "organization_slug": "<string>",
    "sso_jit_provisioning": "<string>",
    "sso_jit_provisioning_allowed_connections": [
      "<string>"
    ],
    "sso_active_connections": [
      {
        "connection_id": "<string>",
        "display_name": "<string>",
        "identity_provider": "<string>"
      }
    ],
    "email_allowed_domains": [
      "<string>"
    ],
    "email_jit_provisioning": "<string>",
    "email_invites": "<string>",
    "auth_methods": "<string>",
    "allowed_auth_methods": [
      "<string>"
    ],
    "mfa_policy": "<string>",
    "rbac_email_implicit_role_assignments": [
      {
        "domain": "<string>",
        "role_id": "<string>"
      }
    ],
    "mfa_methods": "<string>",
    "allowed_mfa_methods": [
      "<string>"
    ],
    "oauth_tenant_jit_provisioning": "<string>",
    "claimed_email_domains": [
      "<string>"
    ],
    "first_party_connected_apps_allowed_type": "<string>",
    "allowed_first_party_connected_apps": [
      "<string>"
    ],
    "third_party_connected_apps_allowed_type": "<string>",
    "allowed_third_party_connected_apps": [
      "<string>"
    ],
    "custom_roles": [
      {
        "role_id": "<string>",
        "description": "<string>",
        "permissions": [
          {
            "resource_id": "<string>",
            "actions": [
              "<string>"
            ]
          }
        ]
      }
    ],
    "trusted_metadata": {},
    "created_at": "<string>",
    "updated_at": "<string>",
    "organization_external_id": "<string>",
    "sso_default_connection_id": "<string>",
    "scim_active_connection": {
      "connection_id": "<string>",
      "display_name": "<string>",
      "bearer_token_last_four": "<string>",
      "bearer_token_expires_at": "<string>"
    },
    "allowed_oauth_tenants": {}
  },
  "status_code": 123
}
Starts a self-serve email update for a specified by their organization_id and member_id. To perform a self-serve update, members must be active and have a verified email address.
RBAC Enforced APIIf a Member Session is passed in the Authorization headers, Stytch will enforce that the Member has permission to take the Action on the Resource prior to honoring the request.To learn more, see the RBAC guide.
The new email address must meet the following requirements:
  • Must not be in use by another member (retired emails count as used until they are unlinked)
  • Must not be updating for another member (i.e. two members cannot attempt to update to the same email at once)
The member will receive an Email Magic Link (or Email OTP Code, if EMAIL_OTP is specified as the delivery method) that expires in 5 minutes. If they do not verify their new email address in that timeframe, the email will be freed up for other members to use. If using Email Magic Links, the magic link will redirect to your login_redirect_url (or the configured default if one isn’t provided), and you should invoke the Authenticate Magic Link endpoint as normal to complete the flow. If using Email OTP Codes, you should invoke the Authenticate Email OTP Code endpoint as normal to complete the flow. Make sure to pass the new email address to the endpoint.

Authorizations

​
Authorization
string
header
required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Headers

​
X-Stytch-Member-Session
string

A Stytch session that can be used to run the request with the given member's permissions.

​
X-Stytch-Member-SessionJWT
string

A Stytch Session JSON Web Token (JWT) that can be used to run the request with the given member's permissions.

Path Parameters

​
organization_id
string
required

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value. You may also use the organization_slug or organization_external_id here as a convenience.

​
member_id
string
required

Globally unique UUID that identifies a specific Member. The member_id is critical to perform operations on a Member, so be sure to preserve this value. You may use an external_id here if one is set for the member.

Body

application/json

Request type

​
email_address
string
required

The new email address for the Member.

​
login_redirect_url
string

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

​
locale
enum<string>

Used to determine which language to use when sending the user this delivery method. Parameter is an IETF BCP 47 language tag, e.g. "en".

Currently supported languages are English ("en"), Spanish ("es"), French ("fr") and Brazilian Portuguese ("pt-br"); if no value is provided, the copy defaults to English.

Request support for additional languages here!

Available options:
en,
es,
pt-br,
fr
​
login_template_id
string

Use a custom template for login emails. By default, it will use your default email template. Templates can be added in the Stytch dashboard using our built-in customization options or custom HTML templates with type “Magic Links - Login”.

​
delivery_method
enum<string>

The method that should be used to verify a member's new email address. The options are EMAIL_MAGIC_LINK or EMAIL_OTP. This field is optional, if no value is provided, EMAIL_MAGIC_LINK will be used.

Available options:
EMAIL_MAGIC_LINK,
EMAIL_OTP

Response

Successful response

​
request_id
string
required

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

​
member_id
string
required

Globally unique UUID that identifies a specific Member.

​
member
object
required
​
organization
object
required
​
status_code
integer<int32>
required

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