https://github.com/stytchauth/stytch-node
Official Stytch Backend SDK for Node.js
https://github.com/stytchauth/stytch-node
javascript nodejs stytch typescript
Last synced: 5 months ago
JSON representation
Official Stytch Backend SDK for Node.js
- Host: GitHub
- URL: https://github.com/stytchauth/stytch-node
- Owner: stytchauth
- License: mit
- Created: 2020-11-04T04:58:27.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-03-31T20:23:32.000Z (about 1 year ago)
- Last Synced: 2025-04-01T07:51:38.277Z (about 1 year ago)
- Topics: javascript, nodejs, stytch, typescript
- Language: TypeScript
- Homepage: https://stytch.com
- Size: 2.51 MB
- Stars: 101
- Watchers: 6
- Forks: 24
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# Stytch Node.js Library
The Stytch Node library makes it easy to use the Stytch user infrastructure API in server-side JavaScript applications.
It pairs well with the Stytch [Web SDK](https://www.npmjs.com/package/@stytch/vanilla-js) or your own custom authentication flow.
This library is tested with all current LTS versions of Node - **18**, and **20**.
## Install
```
npm install stytch
# or
yarn add stytch
```
## Usage
You can find your API credentials in the [Stytch Dashboard](https://stytch.com/dashboard/api-keys).
This client library supports all of Stytch's live products:
**B2C**
- [x] [Email Magic Links](https://stytch.com/docs/api/send-by-email)
- [x] [Embeddable Magic Links](https://stytch.com/docs/api/create-magic-link)
- [x] [OAuth logins](https://stytch.com/docs/api/oauth-google-start)
- [x] [SMS passcodes](https://stytch.com/docs/api/send-otp-by-sms)
- [x] [WhatsApp passcodes](https://stytch.com/docs/api/whatsapp-send)
- [x] [Email passcodes](https://stytch.com/docs/api/send-otp-by-email)
- [x] [Session Management](https://stytch.com/docs/api/session-auth)
- [x] [WebAuthn](https://stytch.com/docs/api/webauthn-register-start)
- [x] [User Management](https://stytch.com/docs/api/create-user)
- [x] [Time-based one-time passcodes (TOTPs)](https://stytch.com/docs/api/totp-create)
- [x] [Crypto wallets](https://stytch.com/docs/api/crypto-wallet-authenticate-start)
- [x] [Passwords](https://stytch.com/docs/api/password-create)
**B2B**
- [x] [Organizations](https://stytch.com/docs/b2b/api/organization-object)
- [x] [Members](https://stytch.com/docs/b2b/api/member-object)
- [x] [RBAC](https://stytch.com/docs/b2b/api/rbac-resource-object)
- [x] [Email Magic Links](https://stytch.com/docs/b2b/api/send-login-signup-email)
- [x] [OAuth logins](https://stytch.com/docs/b2b/api/oauth-google-start)
- [x] [Session Management](https://stytch.com/docs/b2b/api/session-object)
- [x] [Single-Sign On](https://stytch.com/docs/b2b/api/sso-authenticate-start)
- [x] [Discovery](https://stytch.com/docs/b2b/api/discovered-organization-object)
- [x] [Passwords](https://stytch.com/docs/b2b/api/passwords-authenticate)
- [x] [SMS OTP (MFA)](https://stytch.com/docs/b2b/api/otp-sms-send)
- [x] [M2M](https://stytch.com/docs/b2b/api/m2m-client)
**Shared**
- [x] [M2M](https://stytch.com/docs/api/m2m-client)
### Example B2C usage
Create an API client:
```javascript
const stytch = require("stytch");
// Or as an ES6 module:
// import * as stytch from "stytch";
const client = new stytch.Client({
project_id: "project-live-c60c0abe-c25a-4472-a9ed-320c6667d317",
secret: "secret-live-80JASucyk7z_G8Z-7dVwZVGXL5NT_qGAQ2I=",
});
```
Send a magic link by email:
```javascript
client.magicLinks.email
.loginOrCreate({
email: "sandbox@stytch.com",
login_magic_link_url: "https://example.com/authenticate",
signup_magic_link_url: "https://example.com/authenticate",
})
.then((res) => console.log(res))
.catch((err) => console.error(err));
```
Authenticate the token from the magic link:
```javascript
client.magicLinks
.authenticate({ token: "DOYoip3rvIMMW5lgItikFK-Ak1CfMsgjuiCyI7uuU94=" })
.then((res) => console.log(res))
.catch((err) => console.error(err));
```
### Example B2B usage
Create an API client:
```javascript
const stytch = require("stytch");
// Or as an ES6 module:
// import * as stytch from "stytch";
const client = new stytch.B2BClient({
project_id: "project-live-c60c0abe-c25a-4472-a9ed-320c6667d317",
secret: "secret-live-80JASucyk7z_G8Z-7dVwZVGXL5NT_qGAQ2I=",
});
```
Create an organization
```javascript
client.organizations
.create({
organization_name: "Acme Co",
organization_slug: "acme-co",
email_allowed_domains: ["acme.co"],
})
.then((res) => console.log(res))
.catch((err) => console.error(err));
```
Log the first user into the organization
```javascript
client.magicLinks
.loginOrSignup({
organization_id: "organization-id-from-create-response-...",
email_address: "admin@acme.co",
})
.then((res) => console.log(res))
.catch((err) => console.error(err));
```
## TypeScript support
This package includes TypeScript declarations for the Stytch API.
Request and response types will always follow the format `$Vertical$Product$Method(Request|Response)` -
for example the `B2BMagicLinksAuthenticateRequest` maps to the B2B
[Authenticate Magic Link](https://stytch.com/docs/b2b/api/authenticate-magic-link) endpoint, while the
`B2CMagicLinksAuthenticateRequest` maps to the B2C [Authenticate Magic Link](https://stytch.com/docs/api/authenticate-magic-link) endpoint.
## Handling Errors
Stytch errors always include an `error_type` field you can use to identify them:
```javascript
client.magicLinks
.authenticate({ token: "not-a-token!" })
.then((res) => console.log(res))
.catch((err) => {
if (err.error_type === "invalid_token") {
console.log("Whoops! Try again?");
}
});
```
Learn more about errors in the [docs](https://stytch.com/docs/api/errors).
## Customizing the HTTPS Agent
The Stytch client uses [undici](https://github.com/nodejs/undici), the Node fetch implementation. You can pass a custom undici `Dispatcher` to the client for use in requests.
For example, you can enable HTTPS Keep-Alive to avoid the cost of establishing a new connection with the Stytch servers on every request.
```javascript
const dispatcher = new undici.Agent({
keepAliveTimeout: 6e6, // 10 minutes in MS
keepAliveMaxTimeout: 6e6, // 10 minutes in MS
});
const client = new stytch.Client({
project_id: "project-live-c60c0abe-c25a-4472-a9ed-320c6667d317",
secret: "secret-live-80JASucyk7z_G8Z-7dVwZVGXL5NT_qGAQ2I=",
dispatcher,
});
```
## Documentation
See example requests and responses for all the endpoints in the [Stytch API Reference](https://stytch.com/docs/api).
Follow one of the [integration guides](https://stytch.com/docs/guides) or start with one of our [example apps](https://stytch.com/docs/example-apps).
## Support
If you've found a bug, [open an issue](https://github.com/stytchauth/stytch-node/issues/new)!
If you have questions or want help troubleshooting, join us in [Slack](https://stytch.com/docs/resources/support/overview) or email support@stytch.com.
If you've found a security vulnerability, please follow our [responsible disclosure instructions](https://stytch.com/docs/resources/security-and-trust/security#:~:text=Responsible%20disclosure%20program).
## Development
See [DEVELOPMENT.md](DEVELOPMENT.md)
## Code of Conduct
Everyone interacting in the Stytch project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).