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, an SSO redirect, an invite token) 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. An identity has to reach the Active state and have valid credentials to authenticate. Pre-provisioned identities at the Account layer with no password or federation hint stay in the Pending state and can't sign in until credentials are set. 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, sent as a <code>publishable_key</code> 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.