API Authentication

All FileRelay API requests must be authenticated using an API key. Keys are created in the dashboard. Tokens are tied to your user account, not to a specific workspace -- the workspace you want to operate on is selected per request via the URL.

Bearer Token Authentication

Include your API key in the Authorization header of every request using the Bearer scheme:

curl -X GET https://filerelay.dev/api/acme/production/documents \
  -H "Authorization: Bearer fr_live_abc123def456ghi789"

Requests without a valid Authorization header receive a 401 Unauthorized response:

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key."
  }
}

API Key Format

FileRelay API keys use a prefixed format for easy identification:

Prefix	Environment	Example
`fr_live_`	Production	`fr_live_abc123def456ghi789`
`fr_test_`	Test	`fr_test_abc123def456ghi789`

The prefix helps you quickly identify which keys are in use and prevents accidentally using test keys in production systems.

Creating an API Key

API key creation is restricted to workspace Owners and Admins. If you're a Member, ask an admin on the workspace to mint a key for you (or to invite you with a higher role).

To create a new API key:

Navigate to Settings in the sidebar
Select the API Keys tab (visible to Owners and Admins only)
Click Create API Key
Enter a name for the key (e.g., "CI/CD Pipeline", "Monitoring Script")
Click Create

REPLACE: Screenshot of the "Create API Key" dialog with a name field

After creation, the full API key is displayed once. Copy it immediately and store it securely. FileRelay does not store the full key and cannot display it again.

Your new API key:
fr_live_abc123def456ghi789jkl012mno345pqr678

Make sure to copy this key now. You won't be able to see it again.

Addressing a Workspace

Tokens are tied to you, not a workspace. Every workspace-scoped endpoint includes the target workspace in its URL:

https://filerelay.dev/api/{userSlug}/{workspaceSlug}/<resource>

{userSlug} is the slug of the workspace owner (the user who created the workspace, not necessarily the caller), and {workspaceSlug} is the workspace's own slug. Both are visible in the dashboard URL bar when you're inside the workspace.

This means:

One token can address every workspace you're a member of -- just change the path.
A workspace rename or ownership transfer changes the URL. Use the discovery endpoint below to get the current pair.
If you call a workspace you're not a member of, the API responds with 404 Not Found (we never confirm a workspace exists to non-members).

Discovering Workspaces

curl -X GET https://filerelay.dev/api/me/workspaces \
  -H "Authorization: Bearer fr_live_abc123def456"

{
  "data": [
    {
      "user_slug": "acme",
      "workspace_slug": "production",
      "name": "Acme Production",
      "role": "admin"
    },
    {
      "user_slug": "acme",
      "workspace_slug": "development",
      "name": "Acme Development",
      "role": "owner"
    }
  ]
}

Role-Based Permissions

Authorization is checked live on every request against your role in the addressed workspace. If your role on a workspace changes, your existing tokens immediately reflect the new role on that workspace.

Action	Owner	Admin	Member
Read documents, repos, destinations, connections	✓	✓	✓
Retry a failed document	✓	✓	✓
Invoke RFC / BAPI calls	✓	✓	✓
Create / update / delete repos & destinations	✓	✓
Create / update / delete connections	✓	✓
Activate / deactivate / delete certificates	✓	✓
Download certificate PEM	✓	✓
Replay captured requests	✓	✓
Manage webhook endpoints	✓	✓
Manage API keys, invite / re-role team	✓	✓
Transfer ownership, delete workspace	✓

A request that resolves to the workspace but exceeds the caller's role returns 403 Forbidden with code: "forbidden".

Managing API Keys

Viewing Keys

Navigate to Settings > API Keys to see all keys for the current workspace. Each key shows:

Key name
Key prefix (first 8 characters, e.g., fr_live_a...)
Created date
Last used date
Creator

Revoking a Key

To revoke an API key:

Navigate to Settings > API Keys
Find the key you want to revoke
Click Revoke
Confirm the revocation

Revoked keys are immediately invalidated. Any requests using a revoked key receive a 401 Unauthorized response. Revocation cannot be undone -- you must create a new key.

REPLACE: Screenshot of the API keys list showing key names, prefixes, dates, and revoke buttons

Security Best Practices

Never commit API keys to version control. Use environment variables or secrets management tools.
Use descriptive names so you can identify which system uses each key (e.g., "GitHub Actions Deploy", "Grafana Monitoring").
Rotate keys periodically. Create a new key, update your systems, then revoke the old key.
Issue keys from a least-privileged user. Since authorization tracks the caller's live workspace role, mint keys from an account whose role matches the integration's needs -- e.g., a Member account for a read-only monitoring script.
Revoke unused keys. If a key has not been used recently, consider revoking it to reduce your attack surface.
Use test keys for development. Create fr_test_ keys for staging/development, not your production keys.

Troubleshooting

401 Unauthorized

Verify the API key is included in the Authorization header with the Bearer prefix
Check that the key has not been revoked or expired

403 Forbidden

The token is valid and the caller is a member of the addressed workspace, but their role is too low for the action (e.g., a Member trying to create a destination)
Either ask an Admin to perform the action, or have them grant you a higher role

404 Not Found

The {userSlug}/{workspaceSlug} pair in the URL doesn't resolve, or the caller isn't a member of that workspace
Call GET /api/me/workspaces to list the canonical paths for workspaces this token can address
Check for slug typos -- slugs are lowercase, hyphen-separated, and case-sensitive

Next Steps

API Overview -- Base URL, response format, and rate limits
Documents API -- Query and manage documents
Repositories API -- Manage sources programmatically