> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finowl.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate every request with a secret API key sent as a bearer token.

Every request to `https://api.finowl.co/v1` must include your API key in the `Authorization` header:

```http theme={null}
Authorization: Bearer finowl_3f9a2c7e1b4d8a6f0e5c9b21.Xk8vQ2mN...
```

A missing, malformed or revoked key returns `401` with `{"error": {"code": "unauthorized"}}`, and nothing is charged.

## Create a key

1. Open [API Keys](https://app.finowl.co/api-keys) in the dashboard.
2. Select **Create key** and give it a descriptive label, such as `billing-service-prod`.
3. Copy the key immediately. It is shown only once.

Finowl stores only a hash of each key, so a lost key cannot be recovered. Create a new one instead.

## Key format

Keys look like this:

```text theme={null}
finowl_3f9a2c7e1b4d8a6f0e5c9b21.Xk8vQ2mN7pR4sT1uW9yZ0aB3cD6eF8gH2jK5lM7nP0q
```

| Part | Example | Secret? |
| - | - | - |
| Prefix | `finowl_3f9a2c7e1b4d8a6f0e5c9b21` | No |
| Secret | Everything after the `.` | Yes |

The **prefix** (`finowl_` plus 24 characters) is not secret. It is shown in the dashboard so you can tell keys apart, and it is safe to log. The part after the dot is the secret.

<Tip>
  The `finowl_` prefix makes keys easy to find with secret scanners such as GitHub secret scanning or `gitleaks`. Add it to your scanner rules.
</Tip>

## Keep keys safe

<AccordionGroup>
  <Accordion title="Only use keys on your server" icon="server">
    The API does not send CORS headers, so browsers block direct calls. That is deliberate: a key in frontend code or a mobile app can be extracted by anyone. Call Finowl from your backend and return only what your client needs.
  </Accordion>

  <Accordion title="Use one key per service and environment" icon="layer-group">
    Separate keys for production, staging and each service let you revoke one without breaking the others. The dashboard shows when each key was last used, which makes unused keys easy to spot.
  </Accordion>

  <Accordion title="Store keys in a secret manager" icon="vault">
    Load keys from environment variables or a secret manager such as AWS Secrets Manager, Google Secret Manager, Doppler or Vault. Never commit them to source control.
  </Accordion>

  <Accordion title="Never log the Authorization header" icon="eye-slash">
    Check that your HTTP client, proxy and error tracker redact the `Authorization` header. Log the key prefix if you need to know which key was used.
  </Accordion>
</AccordionGroup>

## Rotate a key

Rotate keys on a schedule, when someone with access leaves, or immediately if a key may have leaked.

<Steps>
  <Step title="Create a new key">
    Create a replacement key in the dashboard with a clear label.
  </Step>

  <Step title="Deploy it">
    Update your secret store and deploy. Both keys work at the same time, so there is no downtime.
  </Step>

  <Step title="Revoke the old key">
    Once the old key's **last used** time stops updating, revoke it. Revocation takes effect immediately.
  </Step>
</Steps>

<Warning>
  If a key has leaked, revoke it first and deploy the replacement second. A short outage is better than someone else spending your credits.
</Warning>

## Credits are per account

All keys on an account share the same credit balance and the same [rate limit](/concepts/rate-limits). Revoking a key does not affect your balance.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.