Authentication
How identities sign in. Canopy gives you two paths into the same platform, pick the one that matches how much of the login UI your app wants to own.
Overview
Authentication in Canopy means turning a user's credentials (email + password, a one-time email code, or an SSO redirect) into a signed access token your app can trust. The platform handles password hashing, email verification, password reset, MFA, refresh tokens, and session revocation. Your app delegates as much or as little of that ceremony as you want, then verifies the resulting JWT against a public JWKS endpoint. To sign in, an identity must be active, be a member of the Environment, and have a way to sign in: an identity created without a password can't use one until it sets one, or signs in through SSO. See the Identities overview for the lifecycle and the three-layer model.
Two paths
Both paths land at the same endpoint state, an identity exists, a session is open, and your app has a JWT. The difference is who renders the login screen and where the user types their password.
Hosted Login
Redirect users to Canopy's hosted login page via OAuth2 + PKCE. Canopy owns the UI, the password ceremony, and the email-verification flow. Your app gets a callback with a code, exchanges it for tokens, and you're done.
Direct API
Call the identity-auth API directly from your own login UI. You build the form and submit the user's email and password along with your Environment's publishable key, a non-secret pk_… value you embed in your app and send as the publishable_key field in the JSON request body, so Canopy knows which Environment the login is for. You get a JWT back. Use this when you need full control over the login experience.
Shared infrastructure
Whichever path you pick, the same infrastructure backs both:
Tell us how we can improve this guide.