SDK for Node.js

User sign in

Sign your app's users up and in with a user pool. The platform keeps their passwords; your app gets tokens it can check itself.

Create a user pool

In the dashboard, open User pools, then Create user pool. Open the pool and copy its Pool ID into your .env file:

.env
SECURE_CLOUD_POOL_ID=paste_the_pool_id_here
server.js
const users = cloud.userPool(process.env.SECURE_CLOUD_POOL_ID);

Sign up

server.js
app.post("/sign-up", async (req, res) => {
  const { email, password } = req.body;
  const user = await users.signUp({ email, password });
  res.status(201).json({ id: user.id, email: user.email });
});

A taken email throws CONFLICT (409), and a short or common password BAD_REQUEST (400). errorHandler() sends both to the browser as JSON with a clear message.

Sign in

Signing in gives you two tokens. Keep them in cookies that scripts on the page can't read (httpOnly).

server.js
app.post("/sign-in", async (req, res) => {
  const { email, password } = req.body;
  const session = await users.signIn({ email, password });

  const cookie = { httpOnly: true, sameSite: "lax", secure: process.env.NODE_ENV === "production" };
  res.cookie("access_token", session.accessToken, { ...cookie, maxAge: session.expiresIn * 1000 });
  res.cookie("refresh_token", session.refreshToken, { ...cookie, maxAge: 7 * 24 * 60 * 60 * 1000 });
  res.json({ email: session.user.email });
});
NameTypeWhat it is
accessTokenstringProves who the user is, for a few minutes.
expiresInnumberSeconds until the access token stops working.
refreshTokenstringGets new tokens with refresh(). It works once.
userobjectThe user: id, email, status, attributes.

Protect a route

requireUser() lets signed in users through and puts them on req.user. Everyone else gets a 401.

server.js
app.get("/me", users.requireUser({ cookie: "access_token" }), (req, res) => {
  res.json({ id: req.user.id, email: req.user.email });
});

Without the cookie option it reads an Authorization: Bearer ... header instead, which suits mobile apps. The token is checked on your server with the pool's public keys: no call to the platform for each request.

Keep users signed in

When the access token expires, swap the refresh token for new ones. Always save the new refresh token: an old one used again ends the whole session (someone may have copied it).

server.js
app.post("/refresh", async (req, res) => {
  const session = await users.refresh(req.cookies.refresh_token);
  // ...set both cookies again, as in /sign-in
  res.json({ ok: true });
});

Sign out

server.js
app.post("/sign-out", async (req, res) => {
  await users.signOut(req.cookies.refresh_token);
  res.clearCookie("access_token").clearCookie("refresh_token");
  res.json({ ok: true });
});

Everything a pool can do

NameTypeWhat it is
signUp({ email, password, attributes })PoolUserCreates a user. attributes are your own fields, like { plan: "pro" }.
signIn({ email, password })SessionSigns a user in.
refresh(refreshToken)SessionNew tokens; the old refresh token stops working.
signOut(refreshToken)nothingEnds the session.
verify(accessToken)userChecks a token on your server; throws INVALID_TOKEN if it can't be used.
requireUser({ cookie })middlewareProtects Express routes, as above.
getUser(userId)PoolUserA user's details.
changePassword(userId, { currentPassword, newPassword })nothingChanges a password and ends the user's other sessions.
listRoles(), createRole(), addRole() and moreRoles and permissions: see the next page.
NextRoles and permissions →