Authentication

Authenticate with the FileGuard API

API Key Authentication

All FileGuard API requests require authentication via an API key in the Authorization header.

Authorization: Bearer fg_your_api_key

Creating API Keys

Create API keys from your dashboard or via the API:

curl -X POST "https://api.fileguard.io/api/v1/api-keys" \
  -H "Authorization: Bearer fg_existing_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Upload Key",
    "scopes": ["upload", "download"]
  }'

Store your API key securely! The key value is only returned once during creation and cannot be retrieved later.

API Key Format

FileGuard API keys follow this format:

fg_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456789012

• Prefix: fg_ (identifies FileGuard keys)
• Random string: 38 characters

Scopes

API keys have scopes that control what operations they can perform:

Scope	Description
upload	Upload files to storage
download	Get pre-signed download URLs
metadata	Read file and context metadata, list files
delete	Delete files (soft delete)
admin	Full access - includes all other scopes

Follow the principle of least privilege: only grant the scopes your application actually needs.

Scope Examples

Upload-only key (for client applications):

{
  "name": "Mobile App Upload",
  "scopes": ["upload"]
}

Read-only key (for reporting):

{
  "name": "Analytics Dashboard",
  "scopes": ["metadata"]
}

Full access key (for admin operations):

{
  "name": "Admin Key",
  "scopes": ["admin"]
}

Key Expiration

Set expiration for temporary keys:

{
  "name": "Temporary Integration Key",
  "scopes": ["upload", "download"],
  "expires_in_days": 30
}

Key Status

Status	Description
active	Key is valid and usable
disabled	Key is temporarily disabled (can be re-enabled)
revoked	Key is permanently revoked
expired	Key has passed its expiration date

Error Responses

Invalid API Key (401)

{
  "status": "ERROR",
  "message": "Invalid or expired API key",
  "errors": ["Invalid or expired API key"],
  "timestamp": "2026-01-04T10:00:00Z"
}

Insufficient Scope (403)

{
  "status": "ERROR",
  "message": "API key does not have required scope: upload",
  "errors": ["API key does not have required scope: upload"],
  "timestamp": "2026-01-04T10:00:00Z"
}

Disabled API Key (401)

{
  "status": "ERROR",
  "message": "API key is disabled",
  "errors": ["API key is disabled"],
  "timestamp": "2026-01-04T10:00:00Z"
}

Best Practices

Use environment variables

Never hardcode API keys in source code:

import os
API_KEY = os.environ.get("FILEGUARD_API_KEY")

Rotate keys regularly

Create new keys and revoke old ones periodically, especially for production environments.

Use separate keys per environment

Create different keys for development, staging, and production with appropriate scopes.

Monitor key usage

Check last_used_at to identify unused keys that should be revoked.

Set expiration for integrations

Use expires_in_days for keys shared with third parties or temporary integrations.