netlify-identity
Installation
SKILL.md
Netlify Identity
Auth and user management for a Netlify site without requiring visitors to be Netlify users. Package: @netlify/identity.
Reach for @netlify/identity. Do NOT use the legacy netlify-identity-widget or gotrue-js for new work — same capabilities, simpler API, built-in server-side support.
Footguns — read first
- Identity does not work under
netlify dev. Test auth flows on a deploy — Deploy Previews work. Localnetlify devcannot exercise/.netlify/identity/*. - Never build a from-scratch third-party OAuth flow beside Identity — no provider app registration in code, no
client_id/secretin code, no custom callback token exchange. UseoauthLogin()+handleAuthCallback(). Raw OAuth beside Identity is the single most common source of rework. - Identity config has no public API — dashboard only. Never curl
api.netlify.comto flip/inspect Identity settings, never read tokens from~/Library/Preferences/netlify/config.json, never probe undocumented endpoints. - RBAC redirects without a fallback = raw 404. A visitor lacking the role gets a bare 404 with no way to log in. Always add a fallback rule.
- Server-side
login()/signup()/logout()need CSRF protection. CallverifyRequestOrigin(req)first, or an attacker can log a victim into the attacker's account. - Site-gating ("lock this site to my company", employees-only) → route to netlify-access-control first. Identity is the app-level user layer only.
- On failure (callback 404s,
/.netlify/identity/*unreachable, OAuth doesn't return): surface the error, the dashboard URL, and the setting to check — then stop. Do not invent recovery commands.
Setup
Identity must be enabled in the dashboard first (no API): Project configuration > Identity (https://app.netlify.com/projects/{site_name}/configuration/identity) → Enable Identity.