Forgeplane authentication

Forgeplane supports two external authentication paths: browser sessions for interactive users and X-API-Key for programmatic requests. It currently uses local Forgeplane identities; OIDC, SAML, and other external SSO flows are not implemented.

Choose an authentication method

Client	Mechanism	Use it for
Interactive browser user	Forgeplane email/password session	UI access and human administration
Personal or service-account automation	X-API-Key	API calls with a key-owned lifecycle

Authentication establishes the identity. Organization membership, team roles, resource scope, approvals, and action permissions still determine what that identity may do.

Browser sessions

Interactive users sign in with a Forgeplane email address and password. The coordinator issues a Forgeplane JWT and maintains the browser session in its session cookie.

The BearerAuth scheme in the OpenAPI document represents that same Forgeplane session-JWT path. It is not an API-key transport and does not exchange or validate third-party identity-provider tokens.

API keys

Personal keys and service-account keys authenticate programmatic requests through X-API-Key:

X-API-Key: fpk_xxxxxxxx

The plaintext key is shown once. Forgeplane stores the verifier and exposes only identifying metadata afterward. Keys can have an expiration, record last use, and be revoked without deleting the owning user or service account.

Use a service account when automation needs its own owner, role, lifecycle, or key set. Do not use a human session token as a long-lived automation credential.

Bootstrap the first administrator

The bootstrap endpoint exists to create the first administrator when no normal account can perform setup. It is controlled by FORGEPLANE_ENABLE_ADMIN_BOOTSTRAP and FORGEPLANE_BOOTSTRAP_ADMIN_TOKEN, and is restricted to the installation’s bootstrap conditions.

Disable bootstrap access after the first administrator exists and rotate the bootstrap token out of deployment configuration. See Onboarding for the first-installation sequence.

Request identity

Authenticated requests are classified internally as:

Type	Source
session	Forgeplane browser session or Forgeplane session JWT.
api_key	Personal or service-account key sent in X-API-Key.
system	Internal coordinator operations; unavailable to external clients.

Use Permissions and roles to diagnose the authorization checks that follow authentication.