Authentication

How users and systems authenticate to Forgecroft — OAuth, sessions, and API keys.

Forgecroft supports two authentication flows: OAuth for users and API keys for automation.

User Authentication

Users sign in through OAuth providers (GitHub or Google). After successful authentication, Forgecroft issues a session JWT stored in an fc_session cookie.

OAuth Flow

Navigate to /auth/github or /auth/google to start the OAuth flow
You are redirected to the provider to authorize
After authorization, Forgecroft exchanges the code for a token, fetches your identity, and creates or links your account
A session cookie is set and you are redirected to the console

If you don’t have an organization yet, you’ll be directed to create one via POST /auth/new-account.

Session Management

Sessions are JWTs stored in the fc_session cookie (HttpOnly, secure)
Switch between organizations with POST /auth/switch-org
Log out with POST /auth/logout — this increments your session version, invalidating all existing JWTs immediately
Delete your account with DELETE /auth/account — this cascades to org cleanup

Multi-Org Support

A single user account can belong to multiple organizations. Use GET /me to see all your memberships and POST /auth/switch-org to switch context.

API Key Authentication

API keys authenticate automated systems. They are passed via the Authorization: Bearer header.

Authorization: Bearer fc_live_abc123...

API keys have three dimensions of scoping:

Scope type: org (all resources), project (specific project), or workspace (single workspace)
Action scope: read, write, or admin
Capability scopes: fine-grained permissions like api_keys:read, members:write, billing:read

See the API Keys guide for details on creating and managing keys.

Authentication Levels

Different endpoints require different auth levels:

Level	Methods	Use case
None	No auth required	OAuth start, webhook handlers, Rego playground
User auth	JWT or cookie only	Account management, org switching
Org auth	JWT, cookie, or API key	Most API operations
Runner token	`X-Runner-Token` header	Runner callbacks (internal)