Stytch’s B2B offering is designed to address the unique authentication and user management needs of organization-based applications at every stage of growth.
Introduction
Stytch's B2B authentication platform is built upon two key data entities: Organizations and their Members. This introduction explains their high-level definitions and use cases.
Organizations
The Organization is the top level “tenant” in Stytch’s B2B offering. In more basic terms, an Organization refers to a group of end users who belong together in your application. Most commonly these are businesses and their employees – but it can also include community groups, project collaborators, or other groups of people who want to use your product within a shared entity.
Stytch Organizations are uniquely identified by:
OrganizationID: The Stytch-generated unique ID for the Organization.
Slug: A unique short (typically) human-readable alphanumeric string that you provide. This is often a portion of a URL (e.g. https://ui.honeycomb.io/stytch or https://stytch.slack.com).
Stytch supports two different methods for creating Organizations:
Managed Onboarding: Using direct API calls in order to support manual onboarding processes – often used to restrict access behind a sales team (e.g. Lattice).
Self-Onboarding: A new end user authenticates, verifies their email, and then is able to create a new Organization – used for self-service onboarding flows (e.g. Slack). This can be done by creating an Organization and initial Member as the final step of the Discovery Flow.
Members
Members are the end users who belong to Organizations. They are uniquely identified within an Organization by their email address.
Stytch supports three different methods for creating Members:
Invite: Members can be invited to join a specific Organization by receiving a Magic Link-powered email invitation.
Just-in-Time (JIT) Provisioning: An Organization can specify trusted sources (such as an Identity Provider or a verified email domain) that enable end users to join the Organization without an explicit invite. Through these sources, Members will be automatically created upon successful authentication.
Manual Provisioning: Using direct API calls in order to support user base migrations and manual onboarding processes.
Backend API and SDKs
Stytch's B2B API considers both developer and user experience to ensure fast, safe, and easy authentication flows. Integrate directly with our B2B API in the language of your choice with the help of our comprehensive B2B API Reference, or leverage one of our official Backend SDKs below.
Frontend SDKs
Stytch SDKs allow you to build authentication with minimum backend code. With our SDKs, use your own UI or leverage our highly customizable pre-built UI flows.
JavaScript SDK
Available in vanilla JS and React
iOS SDK
Written in Swift and works with iOS, macOS, and tvOS
Android SDK
Written in Kotlin and works with any Android project
Example apps
Learn more about how Stytch B2B authentication works and get up and running quickly using an example app. Want to dive into the products but not the code? Try out our B2B demo app.
Frontend example apps
Leverage Stytch's flexibility to control authentication from your backend.
Coming Soon
Security
Stytch services are designed, developed, monitored, and updated with security at our core to protect you and your customers’ data and privacy.
Overview
To deliver our services while protecting the confidentiality, integrity, and availability for all our customers, we operate under a shared security responsibility model. This model is adopted by many organizations to identify the respective responsibilities of Stytch and our customers. In this model, Stytch is responsible for the security of the Stytch services and Stytch customers are responsible for the security of their specific configurations within the respective implementations of Stytch services.
Stytch’s responsibility: Stytch is responsible for the security of the services and underlying infrastructure.
Customer responsibility: Stytch customers are responsible for securing their respective configurations and permissions that they enable within Stytch services for their projects. This includes ensuring that customer projects have the correct user permissions set, keys and tokens are appropriately secured within your internal systems, IPs are validated, etc.
Infrastructure & physical security
Stytch leverages highly available and secure cloud infrastructure across multiple platforms to ensure that our services are always available and securely delivered.All Stytch hardware and networking is routinely updated and audited to ensure systems are secure and that least privileged access is followed. Additionally we implement robust logging and audit protocols that allow us high visibility into system use.
Personnel security
Security of Stytch services starts with our employees, which is why we foster a culture of security and approach every question with an eye towards safety. Upon hire and annually thereafter, all employees complete training courses designed to cover Stytch information security practices, privacy practices and requirements, as well as responding to social engineering attacks. Software developers are also required to complete additional courses related to secure software development.Stytch follows the principles of least privilege and segregation of duties wherever possible. Stytch requires that all access to its infrastructure, applications, and data be controlled based on business and operational requirements with users only being provisioned the minimum set of privileges required to perform their required job responsibilities.
When personnel leave Stytch, all of their respective user accounts, passwords, hardware, and badges are revoked.
Service level security
Policies and procedures are in place for handling data processed, stored, and transmitted by Stytch. Data elements are inventoried and classified according to their sensitivity and applicable audience in accordance with Stytch’s Data Classification Policy. Customer confidential data is retained in accordance with contractual terms and regulatory requirements.Stytch requires requests to Stytch services to be encrypted using Transport Layer Security (TLS) using certificates from an established third party certificate authority. Sensitive data is encrypted at rest using Advanced Encryption Standard (AES) 256-bit encryption algorithm or better.
Penetration tests
As part of our security program, we conduct internal security tests, third party penetration tests, and respond to reported vulnerabilities from the public. Identified vulnerabilities are triaged and mitigated in accordance with contractual requirements and internal service level agreements.Responsible disclosure program
Here at Stytch, we take the security of our user’s data and of our services seriously. As such, we encourage responsible security research on Stytch services and products. If you believe you’ve discovered a potential vulnerability, please let us know by emailing us at security@stytch.com. We will acknowledge your email within 2 business days. As public disclosures of a security vulnerability could put the entire Stytch community at risk, we ask that you keep such potential vulnerabilities confidential until we are able to address them. We aim to resolve critical issues within 30 days of disclosure. Please make a good faith effort to avoid violating privacy, destroying data, or interrupting or degrading the Stytch service. Please only interact with accounts you own or for which you have explicit permission from the account holder. While researching, please refrain from:- Distributed Denial of Service (DDoS)
- Spamming
- Social engineering or phishing of Stytch employees or contractors
- Any attacks against Stytch’s physical property or data centers
Privacy
Stytch is committed to protecting the personal data of our customers and their customers. Stytch has in place appropriate data security measures that meet industry standards. We regularly review and make enhancements to our processes, products, documentation, and contracts to help support ours and our customers’ compliance for the processing of personal data.
See our current privacy policy here.
Compliance
Stytch is committed to trust and transparency. As such, we have a publicly available status site at which you can see the current status of our services, past incidents, as well as subscribe to updates.
Stytch is compliant with a range of industry standards and frameworks that assist with your own security and regulatory needs:
- SOC 2 Trust Service Criteria - Stytch maintains a SOC 2 type II report attesting to the company’s compliance with the AICPA’s Trust Service Criteria for Security, Availability, and Confidentiality. For a copy of our report, please reach out to our support team.
- HIPAA - Stytch is compliant with the Health Insurance Portability and Accountability Act as a business associate.
- GDPR & CCPA - Stytch is committed to complying with and helping its customers comply with the General Data Protection Regulation (EU 2016/679 GDPR) and California Consumer Privacy Act (2018 CCPA). We’ve made enhancements to our services, processes, and contract documents in order to help our customers meet their GDPR and CCPA compliance requirements.
- PCI - Stytch fully supports companies that require PCI compliance for their vendors.
- PSD2 - Stytch services can help you meet PSD2 and strong customer authentication requirements.
Resources
Learn more about how Stytch works.
API keys
The Stytch API uses basic authentication with your project_id and secret. There are two environments, TEST and LIVE, and the API keys as well as urls, test.stytch.com and api.stytch.com respectively, are unique to each environment.
Supported browsers
Stytch.js strives to support all recent versions of major browsers:
- Chrome and Safari on all platforms
- Firefox on desktop platforms
- TLS 1.2 must be supported by the browser
If you encounter a bug with other platforms, let us know and we'll prioritize fixing based on popularity of the given browser and severity of the bug.
IP validation
You can specify up to 10 IPs that your requests must come from to ensure that only your servers are able to access the Stytch API. By default we allow all IPs. If you'd like to add IP validation, send an email to support@stytch.com with the subject "IP Validation" with your live project ID and the IPs you'd like to allow (max 10 IPs).
Account enumeration
An account enumeration attack occurs when a bad actor tries to identify valid users, emails, etc within an app's authentication flow. Account enumeration is primarily used to gain information about a system that can be used in further attacks, and does not directly result in compromised accounts.
Example
In order for account enumeration to occur, your app must expose some information about a user's state. For example, if you leverage our Email Magic Links Send endpoint, this endpoint requires that a user already exist before a magic link may be sent. That means if a bad actor enters an arbitrary email address, the Send endpoint will return a 200 success response if that email address exists as a user in your app and a 404 error response if that email address does not exist in your app. Using the Email Magic Links Login or Create endpoint will always send an email, and will always return a consistent response and will not reveal whether the email address already existed in the application or not.This exposes to the bad actor that an email address belongs to a user of your app and the bad actor may leverage this information in a subsequent attack to phish, or compromise this user.
Recommendations
Generally account enumeration does not represent a major risk to your application, non-sensitive consumer applications carry very little risk from account enumeration. In fact, account enumeration via useful and actionable error messages is often helpful for consumer login flows. For example, telling a user that their login failed because they do not have an account is a better user experience than presenting a generic failure message.However if your domain is particularly sensitive to security, e.g. government, fintech, healthcare etc, or your application is at a large enough scale, we do recommend you take a few steps to protect your against account enumeration.
- Don't use error messages that give away key information about why a particular action failed. For example, if an actor initiates a password reset for an account that does not exist, don't show an error message. Instead, show a message to the effect of "If an account is associated with that email, a reset link has been sent."
- Don't expose unmasked Personally Identifiable Information (PII), e.g. only display the last four digits of a phone number in your UI as opposed to the full value.
- Limit how much user state you share with your frontend (user-facing client).
- If you're using our frontend SDKs, the Send methods will error if the user hasn't been pre-created. If this is critical, we recommend disabling the Send methods and exclusively using the LoginOrCreate methods, or using our API directly from your backend.
Redirect URLs
Redirect URLs are used by several Stytch products including Email Magic Links, OAuth, and Passwords (as part of the reset flow). There are four types of redirect urls: login, sign-up, invite, and reset password. These values are set in your code during the associated API call, and tell Stytch where to redirect users upon successful completion of the authentication flow.
By default, all redirect URLs are set to http://localhost:3000 for the Test environment.
Security
For security, a redirect URL must be added in the Dashboard before being used. This prevents bad actors from creating a fake login portal, phishing your users, and redirecting them to a site they control. In the Dashboard, you may set a default redirect URL for each type which allows you to omit setting it as a param when making the associated API call. Redirect URLs are not shared across the Test and Live environments, and must be added to each individually.
Testing
To make testing and development easier, you may use local, non-HTTPS, addresses (e.g. http://localhost:3000) in the Test environment. All Live redirect URLs must use HTTPS.
In the Test environment, you may also use * to specify a wildcard for the domain. For example, https://*.stytch.com. Query parameters cannot contain wildcards and must be an exact match.
This can be helpful in generating preview environments (e.g. https://*.vercel.com). NOTE this does introduce a potential security concern. A bad actor could spoof your subdomain if the environment is hosted on a shared third party service (e.g. https://badactor.vercel.com). This domain would resolve as valid if you are using the wildcard subdomain example in the Dashboard.
Query parameters
Redirect URLs can optionally include query parameters. Query parameters can be useful as an alternative way to persist state outside of browser cookies and local storage during authentication.
URLs must be an exact match. If you have an optional query parameter optional_param, create two redirect URLs: https://www.example.com and https://www.example.com?optional_param={}.
User app state example
An Ecommerce app may want to persist a user’s shopping cart and other app state in their URL so they can serve the user a tailored checkout experience post-login, e.g. https://www.example.com/signup?cart_id=123&promo_banner=true.
Query parameters can be defined as part of the redirect URL in the Dashboard using the pattern param_name={}. In the example above, the developer would need to set the following redirect URL in the Dashboard, https://www.example.com/signup?cart_id={}&promo_banner={}.
Returning to current page example
Another common use case for query parameters is storing the current route location of a user before they authenticate. That way, after a user logs in, your application can parse this value from the query parameters, and redirect the user to the same page that they were on before authenticating.
- Add a redirect URL like https://www.example.com/authenticate?next_route={} in the Dashboard.
- When starting an authentication flow that features a redirect, grab the current page path, and pass the full redirect URL as a parameter in your call to Stytch (e.g. https://www.example.com/authenticate?next_route=/profile/details/)
- After redirecting to https://www.example.com/authenticate and successfully authenticating, finally redirect your user to the path stored in next_route (e.g. https://www.example.com/profile/details/).
Warning! Be sure to validate the next_route contents before doing the final redirect in order to prevent open redirect vulnerabilities.
Native redirect URLs
Native redirect URLs for desktop and mobile applications — for example slack://auth/callback — are also supported.
If you are using Email Magic Links along with native redirect URLs you may need to make additional configuration changes. Review Magic link redirect URL routing for more information.
Event logs
Understand and debug your authentication flows using Stytch event logs. Below is some useful context to help you get started.
Actions
Each event log maps to a specific action, which corresponds to either a Stytch API request (e.g. MagicLinksEmailLoginOrCreate) or a meaningful dashboard request (e.g. CreatePublicToken). Actions help you understand what types of requests are being made.
Status types
You can filter for event logs by status type. The following status types are available:
- start marks the start of a request. It is paired with a subsequent success or error event log.
- success marks the completion of a successful request.
- error marks the failure of a request.
start and success/error event logs are tied together by request ID.
Log retention
Event logs should be available within a minute upon request completion and are currently retained for 30 days.