Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/algolia-security-basics/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill algolia-security-basics. Copyright stays with the author (MIT).

Algolia Security Basics

Overview

Algolia's security model is built around scoped API keys. Every Algolia app has three default keys (Admin, Search-Only, Monitoring). For production, create custom keys with minimal permissions and use Secured API Keys for per-user/per-tenant restrictions.

Prerequisites

• An inventory of current API keys, their consumers, and the indices each consumer needs.
• A secure secret store and a tested rotation process for backend credentials.
• Authority to revoke or restrict exposed keys immediately if the audit finds a violation.

Key Types and Where to Use Them

Instructions

Examples

The environment, scoped-key, secured-key, and rotation examples demonstrate least privilege at each trust boundary. Replace placeholder values through the secret store and validate the resulting ACL before a client receives the key.

Step 1: Environment Variable Setup

# .env (NEVER commit — add to .gitignore)
ALGOLIA_APP_ID=YourApplicationID
ALGOLIA_ADMIN_KEY=admin_api_key_here        # Backend only
ALGOLIA_SEARCH_KEY=search_only_key_here     # OK for frontend

# .gitignore — MUST include:
.env
.env.local
.env.*.local

Step 2: Create Scoped API Keys

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

// Create a write-only key for a specific microservice
const { key: indexingKey } = await client.addApiKey({
  apiKey: {
    acl: ['addObject', 'deleteObject', 'editSettings'],
    description: 'Product sync service — write only',
    indexes: ['products', 'products_staging'],  // Restrict to specific indices
    maxQueriesPerIPPerHour: 5000,
    referers: [],  // Empty = no referer restriction (backend use)
  },
});

// Create a search key restricted to specific referers (frontend)
const { key: frontendKey } = await client.addApiKey({
  apiKey: {
    acl: ['search'],
    description: 'Frontend search — domain-restricted',
    indexes: ['products'],
    referers: ['https://mystore.com/*', 'https://*.mystore.com/*'],
    maxQueriesPerIPPerHour: 1000,
    maxHitsPerQuery: 50,
  },
});

Step 3: Generate Secured API Keys (Per-User Filtering)

// Secured API keys are generated on YOUR server, not via Algolia API.
// They embed restrictions that the client can't bypass.

function generateUserSearchKey(userId: string, tenantId: string): string {
  const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

  return client.generateSecuredApiKey({
    parentApiKey: process.env.ALGOLIA_SEARCH_KEY!,
    restrictions: {
      // User can only see their tenant's data
      filters: `tenant_id:${tenantId}`,
      // Key expires in 1 hour
      validUntil: Math.floor(Date.now() / 1000) + 3600,
      // Restrict to specific indices
      restrictIndices: ['products'],
      // Optional: restrict sources (IPs)
      restrictSources: '',
    },
  });
}

// Usage in your API endpoint:
// const userKey = generateUserSearchKey(req.user.id, req.user.tenantId);
// return { appId: process.env.ALGOLIA_APP_ID, searchKey: userKey };

Step 4: Key Rotation Procedure

async function rotateApiKey(oldKeyDescription: string) {
  const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

  // 1. List keys to find the old one
  const { keys } = await client.listApiKeys();
  const oldKey = keys.find(k => k.description === oldKeyDescription);
  if (!oldKey) throw new Error(`Key not found: ${oldKeyDescription}`);

  // 2. Create new key with same ACL
  const { key: newKey } = await client.addApiKey({
    apiKey: {
      acl: oldKey.acl,
      description: `${oldKeyDescription} (rotated ${new Date().toISOString().split('T')[0]})`,
      indexes: oldKey.indexes || [],
      maxQueriesPerIPPerHour: oldKey.maxQueriesPerIPPerHour || 0,
      referers: oldKey.referers || [],
    },
  });

  console.log(`New key created: ...${newKey.slice(-8)}`);
  console.log('Update your env vars, then delete the old key:');
  console.log(`  client.deleteApiKey({ key: '${oldKey.value}' })`);

  return newKey;
}

Security Checklist

• Admin key in env vars, never in frontend code or git
• .env files in .gitignore
• Frontend uses Search-Only or Secured API key
• Custom keys have minimal ACL (least privilege)
• referers set on frontend keys to prevent abuse
• maxQueriesPerIPPerHour set on all public keys
• Secured API keys have validUntil (expiration)
• Key rotation scheduled quarterly
• Git history scanned for accidentally committed keys

Output

The application separates Admin, search-only, monitoring, custom, and secured keys by use case, with documented ACLs and a revocation path. Browser clients never receive a credential capable of indexing or changing settings.

Error Handling

Resources

• API Keys Guide
• Secured API Keys
• API Key Restrictions

Next Steps

For production deployment, see algolia-prod-checklist.