Authentication

Every request to the FileSafety API must include a valid API key. This page covers the key format, where to find it, how to pass it, and security best practices.

API key format

FileSafety API keys use the following format:

fs_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345

Component	Description
fs_	Product prefix — identifies this as a FileSafety key
live_	Environment indicator — all production keys use live_
24 chars	Cryptographically random base64url-encoded bytes

The full key is 36 characters long. Keys are generated server-side and cannot be customized.

Where to find your key

1. Sign in at app.filesafety.dev/dashboard
2. Click Settings in the sidebar
3. Your API key is listed under the API Keys section
4. Click Copy to copy the full key to your clipboard

How to authenticate

Pass your API key in the x-api-key HTTP header on every request:

curl https://api.filesafety.dev/v1/usage \
  -H "x-api-key: fs_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345"

The API does not support authentication via query parameters, Bearer tokens, or Basic auth. The x-api-key header is the only accepted method.

Invalid or missing key

If the key is missing, malformed, or revoked, the API returns a 401 error:

{
  "error": "Invalid or missing API key"
}

Key rotation

You can regenerate your API key from the dashboard:

1. Go to Settings in the dashboard
2. Click Regenerate API Key
3. Confirm the action

When you regenerate:

• A new key is issued immediately
• The previous key is permanently revoked — any request using the old key will return 401
• There is no grace period. Update your application before or immediately after regenerating.

Zero-downtime rotation

If your application cannot tolerate any failed requests during rotation, use this approach:

1. Deploy a code change that reads the API key from an environment variable (if not already doing so)
2. Regenerate the key in the dashboard
3. Update the environment variable with the new key
4. Restart or redeploy your application

Security best practices

Use environment variables

Never hardcode your API key in source code. Load it from an environment variable at runtime:

# .env (do NOT commit this file)
FILESAFETY_API_KEY=fs_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345

const apiKey = process.env.FILESAFETY_API_KEY;

import os
api_key = os.environ["FILESAFETY_API_KEY"]

Never commit keys to version control

Add your environment file to .gitignore:

.env
.env.local
.env.production

If you accidentally commit a key, regenerate it immediately from the dashboard. Removing the commit from git history is not sufficient — the key should be considered compromised.

Restrict key access

• Only share your API key with team members who need it
• Use a secrets manager (AWS Secrets Manager, HashiCorp Vault, Doppler, etc.) in production environments
• Avoid passing keys through CI/CD logs, Slack messages, or email

Monitor usage

Check GET /v1/usage regularly to detect unexpected spikes that could indicate a leaked key. If you see unusual activity, regenerate the key immediately.

Next steps

• First Scan — Use your API key to submit your first scan
• API Overview — Full API reference