Authentication

ForgeOS supports two authentication methods: session cookies (for browser-based access) and API keys (for MCP and programmatic access).

Authentication methods

Session cookies

Used by the ForgeOS dashboard and browser-based workflows.

Call POST /auth/login with email and password
The response sets a forge_session HttpOnly cookie
Include the cookie on subsequent requests (-b cookies.txt with curl)
A forge_csrf cookie is also set for CSRF protection on state-changing requests

Sessions expire after the configured TTL. Call POST /auth/logout to invalidate early.

API keys

Recommended for MCP servers, CI/CD pipelines, and programmatic access.

Key format: All keys use the fos_ prefix (e.g., fos_a1b2c3d4e5f6...).

Header: Include the key in every request:

X-ForgeOS-API-Key: fos_your_key_here

Key lifecycle:

Action	How
Create	Dashboard or API (after session auth)
Use	`X-ForgeOS-API-Key` header on every request
Rotate	Create a new key, update your config, delete the old key
Revoke	Delete via dashboard or API

Security rules:

Keys are shown once at creation time. Store them immediately.
Maximum 10 keys per user. Delete unused keys before creating new ones.
Only a one-way hash of your key is stored — ForgeOS cannot recover a lost key. Store it immediately.
Never commit keys to version control. Use environment variables.

Agent registration

For autonomous agents that need their own identity:

curl -X POST https://forgeos-api.synctek.io/auth/register-agent \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ci-agent@company.com",
    "password": "secure-agent-password"
  }'

Agent registration returns an API key scoped to the agent identity.

New accounts receive a 14-day Pro trial. After the trial, accounts revert to the Free tier. See pricing for paid plans.

Authentication methods supported

ForgeOS supports two authentication methods: session cookies (for browser-based access) and API keys (for programmatic access via the X-ForgeOS-API-Key header). Public endpoints like login and registration do not require authentication.

Rate limits

Rate limits are enforced per API key.

Endpoint Type	Rate Limit
Standard API	100 requests/minute
AI endpoints (reviews, scoring)	10 requests/minute
Authentication	5 requests/minute

Rate limits are per API key. Contact info@synctek.io for custom limits on Enterprise plans.

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header. Respect this header and use exponential backoff. Maximum 3 retries before surfacing to a human operator.

Error codes

Code	Meaning	Recovery
`401`	Invalid or missing API key / session	Check your API key in the `X-ForgeOS-API-Key` header, or re-authenticate
`402`	AI spend cap exceeded	Upgrade plan or wait for monthly reset
`403`	Insufficient scope or access denied	Check plan tier and project ownership
`409`	Conflict (e.g., email already registered)	Use a different email or log in
`422`	Validation error (e.g., password too short)	Fix the request body per error details
`429`	Rate limit exceeded	Backoff per `Retry-After` header

Security best practices

Use API keys for MCP, not session cookies. API keys are designed for machine access.
Rotate keys regularly. Create a new key, update your config, delete the old one.
Use environment variables for key storage. Never hardcode keys.
One key per integration. If a key is compromised, revoke only that key without disrupting other integrations.
Monitor your usage via GET /api/billing/spend to detect unexpected consumption patterns.