API Keys

API keys let your applications connect to Foir’s public API. Foir provides two types of keys — public and secret — each available in live and test modes, giving you fine-grained control over access and permissions.

Overview

Every request to the Foir API requires an API key. Keys are scoped to a project and carry specific permissions that determine what operations the caller can perform.

Key Types

Public keys are safe to include in browser code, mobile apps, and any client-side application. They can only read content.

Secret keys must never be exposed to browsers or client-side code. They can create, update, delete, and publish content.

Modes

The mode determines what content the key can access:

In the Admin

Creating a Key

1. Go to Settings > Project Settings > API Keys
2. Click Create API Key
3. Fill in the form:
   • Name — something descriptive (e.g., “Production Frontend”, “Staging Backend”)
   • Key Type — PUBLIC or SECRET
   • Mode — Live or Test
   • Permissions — select the scopes this key needs
4. Click Create
5. Copy the key immediately — it is only shown once

Scopes and Permissions

Public Key Scopes

Secret Key Scopes

All public scopes, plus:

The drafts:read scope is restricted to secret keys at key-creation time — public keys (pk_*) are designed to be embeddable in browser bundles and would leak unpublished content. See Preview Mode Access.

Rotating a Key

If a key is compromised or needs to be changed:

1. Go to Settings > Project Settings > API Keys
2. Find the key and click Rotate
3. Copy the new key
4. Update your application
5. The old key stops working immediately

Revoking a Key

To permanently disable a key:

1. Go to Settings > Project Settings > API Keys
2. Find the key and click Revoke

Revoked keys cannot be restored. Create a new key if needed.

Using Keys in Requests

Include the key in the x-api-key header:

curl -X POST https://api.foir.io/graphql \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_abc123..." \
  -d '{"query": "{ records(modelKey: \"page\", limit: 10) { items { id data } } }"}'

In JavaScript:

const response = await fetch('https://api.foir.io/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.FOIR_API_KEY,
  },
  body: JSON.stringify({
    query: `{ records(modelKey: "page", limit: 10) { items { id data } } }`
  }),
});

Environment Variables

Store keys in environment variables, never in code:

# .env.local (do not commit this file)
FOIR_PUBLIC_KEY=pk_live_abc123...
FOIR_SECRET_KEY=sk_live_xyz789...

The Foir CLI also uses the FOIR_API_KEY environment variable for headless authentication:

export FOIR_API_KEY=sk_live_abc123...
foir records list page --json

Via the CLI

# List all API keys for the current project
foir api-keys list
 
# Create a new API key
foir api-keys create --data '{
  "name": "Production Frontend",
  "type": "PUBLIC",
  "mode": "LIVE",
  "scopes": ["records:read", "files:read", "search:read"]
}'
 
# Rotate a key (generates a new key, invalidates the old one)
foir api-keys rotate <id>
 
# Revoke a key (permanently disables it)
foir api-keys revoke <id>

Rate Limits

Each API key has its own per-hour request budget. When exceeded, the API returns 429 Too Many Requests and the response carries a Retry-After header telling you how many seconds to wait.

• Limits are configured per key in the dashboard; the default for new keys is 10,000 requests per hour.
• The window is a sliding 60-minute window — bursts are flattened across the hour rather than refilling on a fixed cadence.
• Every successful response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so you can pace your client.
• Enterprise plans support higher per-key limits — contact support to raise yours.

See Errors & Rate Limits for the full header reference and a recommended client retry/backoff pattern.

Best Practices

Do:

• Use public keys for all client-side code (browsers, mobile apps).
• Store secret keys in environment variables on your server.
• Grant only the minimum scopes each key needs.
• Use descriptive names so you can identify which application uses each key.
• Rotate keys on a regular schedule and immediately if compromised.
• Use test mode keys for development and preview environments.

Do not:

• Commit keys to version control.
• Use secret keys in browser or client-side code.
• Share keys between environments (use separate keys for staging and production).
• Grant more permissions than necessary.