Members overview - Stytch Docs

Member Management

Create a member

Create a new member using the Create Member endpoint:

curl --request POST \
  --url https://test.stytch.com/v1/b2b/organizations/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931/members \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{\n    "email_address": "user@acme.com",\n    "name": "Jane Doe",\n    "create_member_as_pending": false\n  }'

Response:

{
  "status_code": 201,
  "member": {
    "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "email_address": "user@acme.com",
    "name": "Jane Doe",
    "status": "active",
    "trusted_metadata": {},
    "untrusted_metadata": {}
  }
}

Update member details

Update member information using the Update Member endpoint:

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 \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{\n    "name": "Jane Smith",\n    "trusted_metadata": {\n      "role": "admin",\n      "department": "Engineering"\n    }\n  }'

Search members

Find members by email, name, or status using the Search Members endpoint:

curl --request POST \
  --url https://test.stytch.com/v1/b2b/organizations/members/search \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{\n    "organization_ids": ["organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931"],\n    "query": {\n      "operator": "AND",\n      "operands": [\
        {\
          "filter_name": "status",\
          "filter_value": ["active"]\
        }\
      ]\n    }\n  }'

Member Status

A member’s status determines how they interact with your application:

• Active
• Pending
• Invited
• Deleted

Members become active after successfully authenticating at least once. Active members can log in and access the application. When using email authentication, active members receive login emails that route to login_redirect_url.

Members are pending when created via:

• Create Member with create_member_as_pending: true
• Email authentication endpoints that create new members

Pending members become active after their first successful authentication. If sent an invite email, their status changes to invited.

Members are invited when created by sending an invite email. They receive the invite email template. Invited members become active after successfully authenticating through the invite link or signup flow.

Members are marked deleted when:

• Delete Member is called
• Their organization is deleted

All emails and authentication factors are removed when a member is deleted.

Member Metadata

Members support two types of metadata for storing application-specific data:

• Trusted Metadata
• Untrusted Metadata

Secure metadata that can only be modified by backend integrations:

curl --request PUT \
  --url https://test.stytch.com/v1/b2b/organizations/organization-test-.../members/member-test-... \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{\n    "trusted_metadata": {\n      "role": "admin",\n      "billing_status": "paid",\n      "stripe_customer_id": "cus_123456"\n    }\n  }'

Access:

• Backend: Read and write
• Frontend: Read only

Store sensitive fields like roles, permissions, or billing information in trusted metadata.

User-modifiable metadata that can be updated from frontend applications:

curl --request PUT \
  --url https://test.stytch.com/v1/b2b/organizations/organization-test-.../members/member-test-... \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{\n    "untrusted_metadata": {\n      "display_theme": "dark",\n      "preferred_locale": "en-US",\n      "notification_settings": {\n        "email": true,\n        "sms": false\n      }\n    }\n  }'

Access:

• Backend: Read and write
• Frontend: Read and write

Store user preferences and non-sensitive settings in untrusted metadata.

Metadata constraints:

• Maximum 20 top-level keys per metadata object
• Cannot exceed 4KB in size per metadata object

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

See Metadata Update Behavior for how updates are merged.