Keys & Credentials
The credentials your application uses, which integration scenario needs which, and exactly what goes in your app's configuration. Each scenario below is self-contained: find yours and you have everything you need, no cross-referencing.
Overview
Canopy issues a small set of credentials, and which ones you need depends entirely on what your app does. There are four integration scenarios: pick yours below and you'll find a complete checklist plus a copy-paste configuration. The only value every scenario shares is CANOPY_API_URL (where the Canopy API lives); everything else is specific to the scenario.
The four scenarios:
Hosted login (OAuth2)
Your app redirects the browser to Canopy's hosted login page (/oauth/authorize) using the OAuth 2.0 authorization-code flow with PKCE. After the user signs in, Canopy redirects back to your redirect_uri with a one-time code, and your backend exchanges it for tokens at /oauth/token using the client secret.
When to use: You want Canopy to own the login UI (password handling, email verification, MFA, reset) and just hand your backend a signed JWT.
What you need
Your configuration
# Where Canopy lives (every scenario needs this)
CANOPY_API_URL=https://auth.canopy-io.com
# OAuth client: Access Control → Integrations → OAuth Clients, or POST /api/v1/oauth-clients
OAUTH_CLIENT_ID=<your client_id>
OAUTH_CLIENT_SECRET=<shown once at creation> # secret, backend only
OAUTH_REDIRECT_URI=https://app.example.com/callback # must match a registered URI
# Issuer for token verification: Authentication → Signing keys
CANOPY_ISSUER=https://auth.canopy-io.com/environments/<environment_id> # or https://auth.yourapp.com once a custom auth domain is activeFull walkthrough: Hosted login · register the client under OAuth clients.
Direct identity auth
Your app renders its own sign-in form and posts credentials straight to Canopy's identity-auth endpoints (POST /v1/identity/auth/login, …/register, …/forgot-password, …/reset-password). The same signed JWT comes back: no redirects, no consent screen. The request is keyed to one Environment by its publishable key. When the Environment has self-service signup enabled, the same key also powers browser-direct registration.
When to use: You want full control of the login UI, or to keep users on your domain. It's also the path for flows hosted login can't cover, like native mobile sign-in or custom onboarding.
What you need
Your configuration
# Where Canopy lives (every scenario needs this)
CANOPY_API_URL=https://auth.canopy-io.com
# Publishable key: Access Control → Integrations → Publishable Keys, or env card → ⋯ → Publishable Key
PUBLISHABLE_KEY=pk_<your publishable key> # publishable, safe in client code
# Issuer for token verification: Authentication → Signing keys
CANOPY_ISSUER=https://auth.canopy-io.com/environments/<environment_id> # or https://auth.yourapp.com once a custom auth domain is activeFull walkthrough: Direct API.
Server-to-server API
Your backend calls the public API (/api/v1/*) on its own behalf, managing roles, permissions, identities, the hierarchy, OAuth clients and webhooks, or evaluating access, with no end-user in the loop. Every request carries an API key in the X-API-Key header. An API key manages Canopy. It is not how a machine authenticates to your API: for that, register a machine client, give it roles, and have it obtain a token with client_credentials, which your API verifies like a user's. Never present one as a substitute for the other.
When to use: Automation, CI scripts, trusted backend services, and anything that runs without a logged-in person.
What you need
Your configuration
# Where Canopy lives (every scenario needs this)
CANOPY_API_URL=https://auth.canopy-io.com
# API key: Access Control → Integrations → API Keys
API_KEY=cnpy_<shown once at creation> # secret, backend onlyFull walkthrough: API keys.
Handling secrets safely
Rules that apply everywhere
A few rules apply across every scenario, worth knowing wherever you landed above.
Tell us how we can improve this guide.