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

# Authentication

> Learn how to authenticate with the Factify API using API keys and Bearer tokens.

## Overview

All Factify API requests require authentication via Bearer tokens. This guide explains how to obtain and use your API credentials.

## Getting Your API Key

1. Log in to the [Developer Dashboard](https://platform.factify.com)
2. Navigate to **Manage** > **API Keys**
3. Click **Create API Key**
4. Copy your key immediately - it won't be shown again

<Warning>
  Keep your API key secure. Never commit it to version control or expose it in client-side code.
</Warning>

## Using Your API Key

Include your API key in the `Authorization` header of every request:

```bash theme={null}
Authorization: Bearer <YOUR_API_KEY>
```

### SDK Configuration

The SDKs handle authentication automatically once configured:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Factify } from "@factify/sdk";

  const factify = new Factify({
    bearerAuth: process.env.FACTIFY_KEY
  });
  ```

  ```python Python theme={null}
  from factify import Factify
  import os

  client = Factify(bearer_auth=os.environ["FACTIFY_KEY"])
  ```

  ```go Go theme={null}
  import "github.com/factify-inc/factify-go"

  client := factify.New(
      factify.WithBearerAuth(os.Getenv("FACTIFY_KEY")),
  )
  ```
</CodeGroup>

## Environment Variables

We recommend storing your API key in environment variables:

```bash .env theme={null}
FACTIFY_KEY=ffy_live_xxxxxxxxxxxxxxxxxxxx
```

<Tabs>
  <Tab title="Development">
    Use a `.env` file with a tool like `dotenv`:

    ```bash theme={null}
    # .env.local
    FACTIFY_KEY=ffy_test_xxxxxxxxxxxxxxxxxxxx
    ```
  </Tab>

  <Tab title="Production">
    Set environment variables in your hosting platform:

    * **Vercel**: Project Settings > Environment Variables
    * **AWS**: Lambda configuration or Secrets Manager
    * **Heroku**: Config Vars in Settings
  </Tab>
</Tabs>

## API Key Format

Factify API keys follow a structured format that includes environment indicators and embedded identifiers for efficient lookup:

```text theme={null}
ffy_{env}_{base32_uuid7}{base62_random}

Example: ffy_live_01j5q3k8m2n4p6r8t0v2x4z6y8abcdefghijklmnopqrstuvwxyz0123456789a
```

### Key Components

| Component     | Description                                                          |
| ------------- | -------------------------------------------------------------------- |
| `ffy`         | Factify identifier (enables security scanners to detect leaked keys) |
| `live`/`test` | Environment indicator                                                |
| UUID7         | Time-sortable identifier for O(1) database lookup                    |
| Random        | 256-bit entropy secret                                               |

### Environment Types

| Type | Prefix      | Environment | Capabilities                  |
| ---- | ----------- | ----------- | ----------------------------- |
| Test | `ffy_test_` | Sandbox     | Full API access, no real data |
| Live | `ffy_live_` | Production  | Full API access, real data    |

<Warning>
  Environment in the key **must** match the server's runtime environment. Using a `ffy_test_` key against production will return an `invalid_api_key` error.
</Warning>

## Key Rotation

To rotate your API key:

1. Generate a new key in the [Developer Dashboard](https://platform.factify.com)
2. Update your application with the new key
3. Verify the new key works
4. Revoke the old key

<Info>
  You can have up to 5 active API keys at once, allowing for zero-downtime rotation. [Manage API Keys →](https://platform.factify.com)
</Info>

## Authentication Errors

| Status | Error                      | Solution                                                                      |
| ------ | -------------------------- | ----------------------------------------------------------------------------- |
| `401`  | `invalid_api_key`          | Check your API key is correct                                                 |
| `401`  | `expired_api_key`          | Generate a new key in the [Developer Dashboard](https://platform.factify.com) |
| `403`  | `insufficient_permissions` | Contact support to upgrade your plan                                          |

```json Example Error Response theme={null}
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked"
  }
}
```