Quickstart: run locally with authorization code + PKCE

Try it locally in one command

The Quickstart Preview starts Server, Admin, Me, PostgreSQL, and a local Caddy; it does not include the production product-site image. You need Docker Engine and Docker Compose v2:

curl -fsSLO https://pandalabs.cc/downloads/panda-auth-quickstart-0.1.0.tar.gz
tar -xzf panda-auth-quickstart-0.1.0.tar.gz
cd panda-auth-quickstart-0.1.0
bash up.sh

Once it is up, visit:

• Home: http://localhost:8080/
• Admin console: http://localhost:8080/admin/
• Account center: http://localhost:8080/me/
• OIDC Discovery: http://localhost:8080/.well-known/openid-configuration

The script generates a local administrator password and prints it; the password is also stored in quickstart/.env (mode 0600). Local email verification codes are written to container logs; no real mail service is contacted.

The default images come from Tencent Cloud TCR in mainland China:

ccr.ccs.tencentyun.com/panda-auth/

If TCR is unreachable, switch the three application images in quickstart/.env to their GHCR (ghcr.io/pandalabs2026/) counterparts. Images are available for linux/amd64 and linux/arm64.

This is a local trial bundle, not a production deployment; it uses local HTTP, the Development environment, and locally generated preview keys.

Full documentation is in the docs index; product updates are in the changelog.

OIDC integration

PandaAuth implements standard OIDC / OAuth 2.0. Integrating a web app takes only the standard authorization code flow (keeping PKCE enabled at all times is recommended) — no proprietary SDK is required: any standard OIDC client library (OpenIddict Client for .NET, Microsoft.Authentication.WebAssembly.OIDC, NextAuth, and others) works directly.

Prerequisites

• A client created and configured by an administrator (Client ID / redirect URI allowlist / required permissions); client creation and allowlist management currently go through the deployer’s operations channel (integration inquiries: hello@pandalabs.cc).
• Confirm that your deployed instance’s discovery endpoint is reachable:

https://<your-auth-domain>/.well-known/openid-configuration

Integration in five steps

1. Build the authorization request: redirect the browser to /connect/authorize with client_id, redirect_uri, response_type=code, scope (at least openid), and state; also include a code_challenge (S256) and code_challenge_method, and request offline_access to obtain a refresh token.
2. User sign-in: the user authenticates on the PandaAuth-hosted sign-in page (password, MFA, and Passkey are supported).
3. Receive the callback: after authentication, the browser returns to your redirect_uri with code and state; validate state first, then exchange the authorization code for tokens.
4. Exchange for tokens: send a grant_type=authorization_code request to /connect/token with code, redirect_uri, and code_verifier; confidential clients include their client credentials via HTTP Basic.
5. Use and renew: call your APIs with the access token; before the access token expires, use the refresh token to get a new one (grant_type=refresh_token). When tokens are no longer needed, revoking them via /connect/revoke is recommended.

Reference implementation

The official sample samples/PandaAuth.DemoClient (in the server repository) demonstrates the complete flow; its callback URL looks like http://localhost:5201/callback/login/pandaauth.

Next steps

• For the differences between client types and the permission model, see Client types;
• For the precise list of endpoints and scopes, see the Endpoint reference.