Skip to main content

​
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
  2. Navigate to Manage > API Keys
  3. Click Create API Key
  4. 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
});

​
Environment Variables

We recommend storing your API key in environment variables:
.env
FACTIFY_KEY=ffy_live_xxxxxxxxxxxxxxxxxxxx
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

ComponentDescription
ffyFactify identifier (enables security scanners to detect leaked keys)
live/testEnvironment indicator
UUID7Time-sortable identifier for O(1) database lookup
Random256-bit entropy secret

​
Environment Types

TypePrefixEnvironmentCapabilities
Testffy_test_SandboxFull API access, no real data
Liveffy_live_ProductionFull 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:
  1. Generate a new key in the dashboard
  2. Update your application with the new key
  3. Verify the new key works
  4. Revoke the old key
You can have up to 5 active API keys at once, allowing for zero-downtime rotation.

​
Authentication Errors

StatusErrorSolution
401invalid_api_keyCheck your API key is correct
401expired_api_keyGenerate a new key in the dashboard
403insufficient_permissionsContact 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"
  }
}