Creating API Keys

API keys let your application connect to Foir’s API. This guide covers creating and managing API keys.

Key Types

Foir has two types of API keys:

Public Keys (pk_)

• Safe for frontend use - Can be in browser code
• Read-only - Can fetch content but not modify it
• Use for: Websites, mobile apps, any client-side code

Secret Keys (sk_)

• Backend only - Never expose to browsers
• Full access - Can create, update, and delete content
• Use for: Server code, build processes, admin tools

Creating an API Key

1. Go to Project Settings > API Keys
2. Click Create API Key
3. Fill in the form:
   • Name - Something descriptive (e.g., “Production Frontend”)
   • Key Type - PUBLIC or SECRET
   • Environment - Controls what content is visible
   • Permissions - What the key can do
4. Click Create
5. Copy the key immediately - it’s only shown once!

Environments

The environment setting controls what content the key can see:

Permissions

Choose what the key can do:

For Public Keys

• entities:read - Fetch content
• files:read - Access images and files
• routes:resolve - Resolve page URLs
• search:read - Search content

For Secret Keys

All of the above, plus:

• entities:write - Create and update content
• entities:publish - Publish content
• entities:delete - Delete content
• files:write - Upload files
• files:delete - Delete files

Using API Keys

Include the key in your requests:

curl -X POST https://api.foir.io/graphql \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_abc123..." \
  -d '{"query": "{ pages { items { id title } } }"}'

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: `{ pages { items { id title } } }`
  })
});

Environment Variables

Store keys in environment variables, never in code:

# .env.local (don't commit this file)
FOIR_PUBLIC_KEY=pk_live_abc123...
FOIR_SECRET_KEY=sk_live_xyz789...

Managing Keys

Rotating a Key

If a key is compromised or needs to be changed:

1. Go to 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 Project Settings > API Keys
2. Find the key and click Revoke

Revoked keys cannot be restored.

Rate Limits

API keys share rate limits based on your billing plan:

• Limits are per-hour
• All keys in your project share the same pool
• Upgrade your plan for higher limits

Security Best Practices

Do:

• Use PUBLIC keys for client-side code
• Store SECRET keys in environment variables
• Set expiration dates when possible
• Use only the permissions you need
• Rotate keys regularly

Don’t:

• Commit keys to version control
• Use SECRET keys in browsers
• Share keys between environments
• Give keys more access than needed

Troubleshooting

”Invalid API key”

• Check the key is correct and complete
• Make sure it hasn’t been revoked
• Check if it has expired

”API key required”

• Add the x-api-key header to your request

”Secret keys cannot be used from browser”

• You’re using a SECRET key in frontend code
• Switch to a PUBLIC key for browser use

”Insufficient permissions”

• The key doesn’t have the required scope
• Update the key’s permissions in settings

”Rate limit exceeded”

• You’ve hit the hourly request limit
• Wait for the limit to reset, or upgrade your plan

Next Steps

• Getting Started - Set up your first integration
• Using UniformGen - Generate type-safe code
• Using Foir Renderer - Render content in React