FAQ

TL;DR — The questions we see most from teams evaluating AuthPlane for production. If yours isn’t here, Common errors, Debugging, and Getting help probably cover it.

Positioning

What is AuthPlane?

AuthPlane is an open-source OAuth 2.1 authorization server built for the Model Context Protocol, deployed as a single Go binary on your own infrastructure. It issues tokens, publishes discovery, handles consent, and vaults upstream OAuth grants — everything MCP servers need for spec-compliant auth without the SaaS lock-in.

Does AuthPlane replace my existing identity provider?

No. AuthPlane federates to Google Workspace, Okta, Entra ID, Auth0, or any OIDC provider (Guides: Federate to your IdP). You keep your IdP to authenticate the humans; AuthPlane handles the AI agents’ identity and the OAuth token path.

Should I self-host or use a managed service?

It’s a deployment choice. Self-hosting keeps token issuance, identity data, and upstream secrets inside your perimeter with no vendor in the critical path. If you’d rather not operate it yourself, AuthPlane’s managed cloud offering (on the way) is the same product with an identical wire protocol — you can start self-hosted and move later, or vice versa.

How does AuthPlane compare to Auth0 / Keycloak / rolling your own?

  • Auth0 / Descope / WorkOS — general-purpose SaaS identity, per-MAU billing, not purpose-built for MCP. AuthPlane is MCP-first, and available self-hosted (flat cost, your perimeter) or managed.
  • Keycloak — powerful but heavyweight and not built for MCP. AuthPlane is purpose-built for OAuth 2.1 + MCP Authorization spec.
  • Rolling your own — you’d need to implement 16 RFCs correctly and stay on top of revisions. AuthPlane implements them and ships a conformance test suite.

How long does it take to get running?

One docker run brings up the OAuth 2.1 endpoints and admin UI. Most teams have a runnable example registered within ten minutes. See Quickstart.

Compliance & security

Is AuthPlane SOC 2 certified?

Not as a shipping vendor, no. AuthPlane is software you self-host — the certification model that applies to your deployment is your own organization’s. The code is AGPL-3.0 and reviewable; the threat model and token design are documented; security disclosures go through GitHub Private Vulnerability Reporting (see Reporting vulnerabilities).

Can I run it air-gapped?

Yes. The binary makes zero outbound network calls unless you explicitly enable error reporting or configure OIDC federation to an external IdP. Both are opt-in.

What RFCs does AuthPlane implement?

The full list is in Reference: RFC compliance — 16 RFCs including OAuth 2.1 (auth code + PKCE + refresh + client_credentials + token exchange + JWT bearer), DPoP, DCR, PRM, resource indicators, introspection, revocation, JWT AT, and problem details. Every deviation is opt-in and documented. Note: OAuth 2.1 itself is still an active IETF draft (draft-ietf-oauth-v2-1), not a published RFC — AuthPlane implements the latest revision.

How are secrets handled?

Session secrets, admin API keys, and upstream OAuth client secrets are all env-var only — never in YAML. Refresh grants stored in broker_grants are encrypted at rest (AES-256-GCM or Vault Transit). Signing keys either live in a permission-restricted keyfile, encrypted in Postgres, or in HashiCorp Vault Transit (never on disk).

Deployment & operations

Do you support multi-tenant isolation?

First-class multi-tenant isolation is post-v1.0. Today, full isolation means separate AuthPlane instances per tenant — which is the same model most regulated environments require anyway. All AuthPlane state (clients, users, resources, providers, grants, issuances, keys) lives in one DB; if you need hard isolation, one AuthPlane per tenant is the pattern.

Minimum hardware?

Single instance: 512 MB RAM, 1 vCPU handles typical loads (< 100 TPS token issuance). The binary is < 50 MB. SQLite storage: as much disk as your issuances table can grow to (~1 KB per token issuance row). Postgres storage: as much as your Postgres instance can hold.

How do I set up HA?

Postgres for storage (storage.driver: postgres), vault_transit or postgres_key for signing (so keys are shared across instances), stateless replicas behind a load balancer, LISTEN/NOTIFY handles config propagation. See Operate: Kubernetes for the Helm chart with autoscaling.enabled + podDisruptionBudget.

What’s the performance impact on my MCP server?

Effectively none on the request path. The SDK validates tokens locally against the JWKS (cached). AuthPlane itself only handles token issuance, refresh, and admin operations — none of which sit in front of your tool calls.

Do I need to run authserver purge?

Yes if you enable DPoP, client credentials, or XAA — expired-data tables (dpop_nonces, machine_tokens, assertion_jti) grow unbounded without purging. Schedule via systemd timer, Docker sidecar, or Kubernetes CronJob. Recipes in Operate: Backup, upgrade, purge.

How do I migrate from SQLite to Postgres?

  • Point storage.driver: postgres and set storage.postgres.dsn.
  • Run authserver migrate against the empty Postgres DB.
  • Data migration between drivers is manual today — no authserver export/import yet. For most deployments the practical path is: stand up the Postgres instance fresh (no historical data), rotate credentials so clients re-register via DCR. Grants are per-user and rebuild organically as users next authenticate.

How do I upgrade AuthPlane?

docker pull (or download the new binary), run authserver migrate (idempotent — safe to run against an already-migrated DB), restart. Migrations are forward-only; there’s no rollback. Read the release notes before major-version bumps. See Operate: Backup, upgrade, purge → Upgrade.

DPoP vs mTLS — which should I use?

Different scopes. mTLS binds a connection to a client certificate. DPoP binds a token to a client key pair — the token remains usable across connections, but only by the holder of the corresponding private key. In multi-hop deployments, DPoP proofs travel with the token; mTLS terminates at the first hop. Use DPoP for tokens that transit multiple services; use mTLS for a hardened perimeter around AuthPlane itself if you want it.

Interop

Which MCP clients has AuthPlane been tested with?

Automated tests: MCP Inspector 0.14.x (full flow). Known-bugs handled: Claude Code (AUTHPLANE_OAUTH_REQUIRE_SCOPE=false workaround). Manually validated: Claude Desktop, Cursor. Pending validation: VS Code Copilot Chat. Full matrix in compatibility.md in the authserver repo, which is the living source of truth.

Which languages/frameworks have SDKs?

Python (official MCP SDK + PrefectHQ FastMCP), TypeScript (official MCP SDK, punkpeye FastMCP, Hono, NestJS), Go (official MCP SDK, mark3labs/mcp-go, generic net/http). See SDKs overview for the full matrix. C#, Java, and Rust SDKs are in the codebase but not yet listed as first-class options in these docs.

Where to next