---
title: API Authentication
description: "How to authenticate with the FileRelay API using API keys, including creating, scoping, and revoking keys."
---

# 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:

```bash
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:

```json
{
  "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:

1. Navigate to **Settings** in the sidebar
2. Select the **API Keys** tab (visible to Owners and Admins only)
3. Click **Create API Key**
4. Enter a **name** for the key (e.g., "CI/CD Pipeline", "Monitoring Script")
5. 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

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

```json
{
  "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:

1. Navigate to **Settings > API Keys**
2. Find the key you want to revoke
3. Click **Revoke**
4. 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](/docs/api/overview) -- Base URL, response format, and rate limits
- [Documents API](/docs/api/documents) -- Query and manage documents
- [Repositories API](/docs/api/repositories) -- Manage sources programmatically