Skip to main content
POST
/
v1
/
b2b
/
magic_links
/
email
/
invite
C#
// POST /v1/b2b/magic_links/email/invite
const stytch = require('stytch');

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

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

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

client.MagicLinks.Email.Invite(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
}
Send an invite email to a new to join an . The Member will be created with a status of invited 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. The magic link invite will be valid and can be authenticated for 1 week, after which the Member will need to to be sent a new invite email.
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.

​
Revoke an invite

To revoke an existing invite, use the Delete Member endpoint. This will both delete the invited Member from the target Organization and revoke all existing invite emails.

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.

Body

application/json

Request type

​
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.

​
email_address
string
required

The email address of the Member.

​
invite_redirect_url
string

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

​
invited_by_member_id
string

The member_id of the Member who sends the invite.

​
name
string

The name of the Member.

​
trusted_metadata
object

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

​
untrusted_metadata
object

An arbitrary JSON object of application-specific data. These fields can be edited directly by the frontend SDK, and should not be used to store critical information. See the Metadata resource for complete field behavior details.

​
invite_template_id
string

Use a custom template for invite 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 - Invite”.

​
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
​
roles
string[]

Roles to explicitly assign to this Member. See the RBAC guide for more information about role assignment.

​
invite_expiration_minutes
integer<int32>

The expiration time, in minutes, for an invite email. If not accepted within this time frame, the invite will need to be resent. Defaults to 10080 (1 week) with a minimum of 5 and a maximum of 10080.

Required range: x >= 0

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.