Authentication

Authenticating requests

Every /v1 endpoint requires an API key. Forge uses a single authentication scheme: a bearer token passed in the Authorization header.

Creating a key

Sign up at forge-api.dev/signup, then open the dashboard and go to the API keys tab to create one. Keys are prefixed fg_live_ so they're easy to spot in logs and secret scanners.

The full key value is shown exactly once, at the moment you create it. Forge stores only a hash server-side for verification, so there is no way to retrieve a lost key — you'll need to revoke it and create a new one.

Sending the key

Pass the key as a Bearer token in the Authorization header on every request:

curl 'https://forge-api.dev/v1/weather?city=paris' \
  -H 'Authorization: Bearer fg_live_xxxxxxxx'

In the SDKs, the key is supplied once when you construct the client:

from forge_api import Forge

forge = Forge('fg_live_xxxxxxxx')
wx = forge.weather(lat=48.85, lon=2.35)

Missing or invalid keys

If a request is made without an Authorization header, Forge returns 401:

{
  "status": "error",
  "error": {
    "code": "missing_api_key",
    "message": "No API key provided. Pass your key in the Authorization header: Bearer fg_live_...",
    "doc_url": "https://forge-api.dev/docs/authentication"
  }
}

If the header is present but the key is malformed, revoked, or unknown, you'll get 401 with "code": "invalid_api_key" instead.

Key hygiene

• Never commit keys to source control or embed them in client-side JavaScript — treat fg_live_ keys like passwords.
• Create separate keys per environment (local-dev, staging, production) so you can revoke one without affecting the others.
• Rotate a key by creating a new one in the dashboard, deploying it, then revoking the old key once traffic has fully cut over.
• If you suspect a key has leaked, revoke it immediately from the API keys tab — revocation takes effect within seconds.

A note on /v0

The deprecated /v0 endpoints use a different scheme — the key is passed as a key query parameter instead of a header. This is a legacy behavior kept only for backwards compatibility; do not use query-parameter auth for new integrations. See migrating from v0 for details.

Next steps

• Review rate limits to understand how limits are applied per key.
• See errors for the full list of error codes you may encounter.