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:
SECURE_CLOUD_POOL_ID=paste_the_pool_id_hereconst users = cloud.userPool(process.env.SECURE_CLOUD_POOL_ID);Sign up
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).
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 });
});| Name | Type | What it is |
|---|---|---|
accessToken | string | Proves who the user is, for a few minutes. |
expiresIn | number | Seconds until the access token stops working. |
refreshToken | string | Gets new tokens with refresh(). It works once. |
user | object | The 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.
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).
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
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
| Name | Type | What it is |
|---|---|---|
signUp({ email, password, attributes }) | PoolUser | Creates a user. attributes are your own fields, like { plan: "pro" }. |
signIn({ email, password }) | Session | Signs a user in. |
refresh(refreshToken) | Session | New tokens; the old refresh token stops working. |
signOut(refreshToken) | nothing | Ends the session. |
verify(accessToken) | user | Checks a token on your server; throws INVALID_TOKEN if it can't be used. |
requireUser({ cookie }) | middleware | Protects Express routes, as above. |
getUser(userId) | PoolUser | A user's details. |
changePassword(userId, { currentPassword, newPassword }) | nothing | Changes a password and ends the user's other sessions. |
listRoles(), createRole(), addRole() and more | Roles and permissions: see the next page. |