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 records a server-side session, issues a Forgeplane JWT that names it, and keeps the JWT in the browser’s session cookie. A session lasts 24 hours.

The coordinator accepts a session JWT only while its server-side session is active:

• Signing out revokes that session immediately. The user’s other sessions stay valid.
• Any password change, including a password reset, an administrator-set password, and administrator recovery, revokes all of the user’s sessions. After a profile password change, the browser that submitted it receives a new session.

The Authorization: Bearer <session-jwt> path uses that same Forgeplane session JWT. It is not an API-key transport and does not exchange or validate third-party identity-provider tokens.

User enabled state

The User resource exposes a required enabled boolean and new users start enabled. Only a principal with platform user:manage (the built-in admin role) may change another user’s enabled state through the User API; the authenticated user cannot change its own enabled state.

When a user is disabled, browser sign-in fails and existing sessions or user-owned API credentials are rejected when the coordinator refreshes the current principal. The disabled user has no effective platform assignments. A user-owned service account remains a separate Principal: its own role, credentials, and enabled state are not inherited from the owner User and are not disabled when that User is disabled.

Change a password

An authenticated user changes its own password through the profile flow at POST /profile/password. The form requires current_password, new_password, and confirm_password. Forgeplane verifies the current password; the new password must contain non-space characters, be at least eight characters long, and match the confirmation.

Do not send a password field in PUT /api/v1/users/{id} when the target is the authenticated user. The self policy rejects that update; use the profile flow instead. An administrator-managed update to another user may set password through the User API, where the server hashes it. Client-managed password_hash values are not accepted.

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.

Regenerating the API key on your profile page revokes the previous profile key in the same step. Personal keys you created under their own names are not affected; revoke those individually.

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

Bootstrap creates the initial administrator only when the installation has neither users nor effective platform administrators. Complete database initialization and start the coordinator before using it. Source development can create a disposable account automatically; see Quickstart for that separate path.

1. Temporarily set FORGEPLANE_ENABLE_ADMIN_BOOTSTRAP=true on the coordinator and supply a unique FORGEPLANE_BOOTSTRAP_ADMIN_TOKEN through protected deployment configuration. For Helm, use coordinator.env.enableAdminBootstrap=true and the runtime Secret’s bootstrap-admin-token key.
2. Connect directly through the coordinator’s loopback interface, such as an authenticated port-forward bound to 127.0.0.1. Do not use the public ingress or a reverse proxy: forwarded client headers are rejected.
3. Create a private admin-bootstrap.json file with permissions 0600. Replace the example values with your email, name, and a strong unique password of at least eight characters. Do not commit this file or put credentials in shell history.

{
  "email": "you@example.com",
  "name": "Administrator",
  "password": "<your strong unique password>"
}

Send the request to the loopback coordinator, with the configured token supplied securely in your shell environment:

curl --fail-with-body --silent --show-error \
  -X POST 'http://127.0.0.1:8080/bootstrap/admin' \
  -H "X-Forgeplane-Bootstrap-Token: $FORGEPLANE_BOOTSTRAP_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @admin-bootstrap.json

A successful request returns 201 Created. Delete the temporary JSON file and local token copies after the request, including on failure. After success, disable FORGEPLANE_ENABLE_ADMIN_BOOTSTRAP and restart or roll the coordinator; for Helm, set coordinator.env.enableAdminBootstrap=false. Sign in with the new account and continue with Onboarding. Bootstrap is not an account-recovery endpoint and cannot add users to an initialized installation.

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.