Authentication

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

Log in to the Developer Dashboard
Navigate to Manage > API Keys
Click Create API Key
Copy your key immediately - it won’t be shown again

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

Using Your API Key

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

Authorization: Bearer <YOUR_API_KEY>

SDK Configuration

The SDKs handle authentication automatically once configured:

import { Factify } from "@factify/sdk";

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

from factify import Factify
import os

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

import "github.com/factify-inc/factify-go"

client := factify.New(
    factify.WithBearerAuth(os.Getenv("FACTIFY_KEY")),
)

Environment Variables

We recommend storing your API key in environment variables:

.env

FACTIFY_KEY=ffy_live_xxxxxxxxxxxxxxxxxxxx

Development
Production

Use a .env file with a tool like dotenv:

# .env.local
FACTIFY_KEY=ffy_test_xxxxxxxxxxxxxxxxxxxx

API Key Format

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

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

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.

Key Rotation

To rotate your API key:

Generate a new key in the Developer Dashboard
Update your application with the new key
Verify the new key works
Revoke the old key

You can have up to 5 active API keys at once, allowing for zero-downtime rotation. Manage API Keys →

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
`403`	`insufficient_permissions`	Contact support to upgrade your plan

Example Error Response

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked"
  }
}

Quick Start

Using the SDKs

Overview

Getting Your API Key

Using Your API Key

SDK Configuration

Environment Variables

API Key Format

Key Components

Environment Types

Key Rotation

Authentication Errors

​Overview

​Getting Your API Key

​Using Your API Key

​SDK Configuration

​Environment Variables

​API Key Format

​Key Components

​Environment Types

​Key Rotation

​Authentication Errors

Overview

Getting Your API Key

Using Your API Key

SDK Configuration

Environment Variables

API Key Format

Key Components

Environment Types

Key Rotation

Authentication Errors