Authentication

Forgecroft has two authentication methods: OAuth sessions for interactive users and API keys for automation.

User Authentication (OAuth)

Users sign in through GitHub or Google OAuth.

Flow

1. Navigate to /auth/github or /auth/google.
2. Authorize with the provider.
3. Forgecroft exchanges the authorization code for a token, fetches your identity, and creates or links your account.
4. A session cookie is set and you are redirected to the console.

If you have no organization yet, you are directed to create one via POST /auth/new-account.

Sessions

After OAuth completes, Forgecroft issues a JWT stored in an fc_session cookie (HttpOnly, Secure). This JWT is your session — every authenticated request includes it automatically.

• Switch organization: POST /auth/switch-org (a single user account can belong to multiple organizations)
• View memberships: GET /me returns your profile and all org memberships
• Log out: POST /auth/logout increments your session version, which invalidates all existing JWTs immediately — not just the current browser
• Delete account: DELETE /auth/account cascades to org cleanup

API Key Authentication

API keys authenticate automated systems: CI pipelines, the CLI, and coding agents. Pass them via the Authorization header:

Authorization: Bearer fc_live_abc123...

API keys have three dimensions of scoping:

• Scope type: org (all resources) or project (one project)
• 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 creating and managing keys.

Authentication Levels

Different endpoints require different credentials:

Level	Method	Use case
None	No auth required	OAuth start, webhook handlers
User auth	Session JWT only	Account management, org switching
Org auth	Session JWT or API key	Most API operations

Related Endpoints

• GET /auth/providers — available OAuth providers
• GET /me — current user profile and org memberships
• POST /auth/switch-org — switch org context
• POST /auth/logout — invalidate all sessions
• GET /whoami — identity and scope info (works with both sessions and API keys)