How to Authenticate Your FileRouter REST API Requests

Every request to a /api/v1/ endpoint must include a valid API key. FileRouter uses standard HTTP Bearer authentication — you send your key in the Authorization header, and the API validates it on every request. There are no cookies, sessions, or OAuth flows for the REST API.

Get Your API Key

You create and manage API keys from the FileRouter dashboard at filerouter.dev. Each key ties to your account and scopes permissions accordingly. Treat your API key like a password — don’t commit it to version control or expose it in client-side code.

Send the Authorization Header

Include the following header on every API request:

Authorization: Bearer <your-api-key>

curl https://filerouter.dev/api/v1/jobs \
  --request POST \
  --header "Authorization: Bearer $FILEROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: my-unique-key-001" \
  --data '{
    "operation": "parse",
    "outputs": ["markdown"],
    "source": { "url": "https://example.com/report.pdf" }
  }'

import { FileRouterClient } from "@file_router/sdk"

// The client reads FILEROUTER_API_KEY from the environment automatically.
const client = new FileRouterClient()

const result = await client.parse("https://example.com/report.pdf", {
  outputs: ["markdown"],
})

The TypeScript FileRouterClient reads FILEROUTER_API_KEY from your environment automatically. You don’t need to set the header manually when using the SDK.

401 Unauthorized

If you omit the Authorization header, send an invalid key, or use a key that has been disabled or has expired, the API returns HTTP 401 with an application/problem+json body:

401 error response

{
  "status": 401,
  "code": "unauthorized",
  "detail": "Missing FileRouter API key.",
  "title": "Unauthorized",
  "type": "https://filerouter.dev/problems/unauthorized",
  "instance": "/api/v1/jobs",
  "request_id": "01J2Y9QX3MXJQHD2YQ9N7J93M4"
}

Show 401 response fields

status

number

required

The HTTP status code. Always 401 for authentication failures.

code

string

required

A machine-readable error code identifying the specific failure reason (e.g., unauthorized).

detail

string

required

A human-readable explanation of the error. For missing keys, this is "Missing FileRouter API key.".

title

string

required

A short, human-readable summary of the problem type (e.g., "Unauthorized").

type

string

required

A URI that identifies the problem type. You can use this as a stable identifier in error-handling code.

instance

string

required

The request path that triggered this error (e.g., /api/v1/jobs).

request_id

string

required

The unique request identifier. This matches the X-Request-ID response header. Include this value when contacting support.

API keys can be disabled or expired by you or an administrator. If you receive a 401 and your key looks correct, open the FileRouter dashboard to verify the key is still active and hasn’t passed its expiry date.

Security Best Practices

Store your API key in an environment variable (e.g., FILEROUTER_API_KEY) rather than hardcoding it.
Rotate keys regularly and revoke any key you suspect has been compromised.
Use separate keys for development and production environments so you can revoke one without affecting the other.

Overview

Endpoints

How to Authenticate Your FileRouter REST API Requests

Get Your API Key

Send the Authorization Header

401 Unauthorized

Security Best Practices

​Get Your API Key

​Send the Authorization Header

​401 Unauthorized

​Security Best Practices

Get Your API Key

Send the Authorization Header

401 Unauthorized

Security Best Practices