> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filerouter.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Authenticate Your FileRouter REST API Requests

> How to authenticate FileRouter REST API requests using a Bearer token API key, including the 401 error shape and tips for managing key lifecycle.

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](https://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>
```

<CodeGroup>
  ```bash title="Authenticated request (curl)" theme={null}
  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" }
    }'
  ```

  ```typescript title="Authenticated request (TypeScript SDK)" theme={null}
  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"],
  })
  ```
</CodeGroup>

<Note>
  The TypeScript `FileRouterClient` reads `FILEROUTER_API_KEY` from your environment automatically. You don't need to set the header manually when using the SDK.
</Note>

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

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

<Expandable title="401 response fields">
  <ResponseField name="status" type="number" required>
    The HTTP status code. Always `401` for authentication failures.
  </ResponseField>

  <ResponseField name="code" type="string" required>
    A machine-readable error code identifying the specific failure reason (e.g., `unauthorized`).
  </ResponseField>

  <ResponseField name="detail" type="string" required>
    A human-readable explanation of the error. For missing keys, this is `"Missing FileRouter API key."`.
  </ResponseField>

  <ResponseField name="title" type="string" required>
    A short, human-readable summary of the problem type (e.g., `"Unauthorized"`).
  </ResponseField>

  <ResponseField name="type" type="string" required>
    A URI that identifies the problem type. You can use this as a stable identifier in error-handling code.
  </ResponseField>

  <ResponseField name="instance" type="string" required>
    The request path that triggered this error (e.g., `/api/v1/jobs`).
  </ResponseField>

  <ResponseField name="request_id" type="string" required>
    The unique request identifier. This matches the `X-Request-ID` response header. Include this value when contacting support.
  </ResponseField>
</Expandable>

<Tip>
  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](https://filerouter.dev) to verify the key is still active and hasn't passed its expiry date.
</Tip>

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