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

# Authenticate with FileRouter: API Keys and CLI Login

> Learn how to obtain a FileRouter API key, pass it in SDK and REST requests, and log in through the CLI using browser-based device authorization.

Every request to the hosted FileRouter service must carry a valid API key. You create this key once through [filerouter.dev](https://filerouter.dev), then supply it in one of several ways depending on which surface you use. This page covers all three: the `Authorization` header for direct REST calls, the `FileRouterClient` constructor option for the TypeScript SDK, and the `npx @file_router/cli login` command for the terminal.

## Get an API key

Visit [filerouter.dev](https://filerouter.dev), sign in, and create an API key from your account dashboard. Keep it secret — treat it the same way you would treat a password.

## Pass the key in REST requests

Every request to the hosted API must include an `Authorization` header with your key as a Bearer token.

```http theme={null}
Authorization: Bearer <your_api_key>
```

The REST API enforces this on every endpoint. If the header is missing or the key is disabled, the API returns a `401` response:

```json theme={null}
{ "detail": "Missing FileRouter API key." }
```

<Warning>
  Never commit your API key to source control. Use environment variables or a secrets manager to inject it at runtime.
</Warning>

## Use the key in the TypeScript SDK

The `FileRouterClient` constructor accepts an `apiKey` option. If you omit it, the client automatically reads the `FILEROUTER_API_KEY` environment variable.

<Tabs>
  <Tab title="Explicit option">
    ```ts index.ts theme={null}
    import { FileRouterClient } from "@file_router/sdk"

    const client = new FileRouterClient({ apiKey: process.env.FILEROUTER_API_KEY })
    ```
  </Tab>

  <Tab title="Environment variable (implicit)">
    ```ts index.ts theme={null}
    import { FileRouterClient } from "@file_router/sdk"

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

    Set the variable in your shell or `.env` file before running your application:

    ```bash .env theme={null}
    FILEROUTER_API_KEY=your_api_key_here
    ```
  </Tab>
</Tabs>

If neither the option nor the environment variable is present when you construct the client, it throws a `FileRouterError` with code `Auth` immediately — before you make any network calls.

## Log in with the CLI

The CLI uses a browser-based device authorization flow so you never have to copy-paste a key manually. Run `login` once and the CLI saves your key locally for all future commands.

<Steps>
  ### Run the login command

  ```bash terminal theme={null}
  npx @file_router/cli login
  ```

  ### Authorize in your browser

  The CLI prints a short user code and opens your browser to [filerouter.dev](https://filerouter.dev). You will see a prompt asking you to confirm the code displayed in your terminal.

  ```
  Open https://filerouter.dev/api/auth/device/code
  Code: ABCD-1234
  ```

  ### Confirm the code

  Enter or confirm the code in your browser. Once you approve the authorization, the CLI exchanges the device code for an access token and automatically creates a dedicated API key named **FileRouter CLI**.

  ### Done

  The CLI prints `Authenticated.` and saves your API key to `~/.config/filerouter/config.json` (or `$XDG_CONFIG_HOME/filerouter/config.json` if that variable is set). The file is written with mode `0600` so only your user account can read it.

  ```bash terminal theme={null}
  npx @file_router/cli parse report.pdf
  ```

  All subsequent CLI commands use the saved key with no further configuration.
</Steps>

<Info>
  The device authorization session is closed immediately after the CLI creates your API key. FileRouter does not retain your OAuth token.
</Info>

## API key errors

| Situation                      | HTTP status | Response body                                 |
| ------------------------------ | ----------- | --------------------------------------------- |
| `Authorization` header missing | `401`       | `{ "detail": "Missing FileRouter API key." }` |
| Key disabled or expired        | `401`       | `{ "detail": "Missing FileRouter API key." }` |

If you receive a `401`, check that the `FILEROUTER_API_KEY` environment variable is set correctly or that the key you created in the dashboard has not been revoked.

## BYOK mode — no FileRouter key required

<Tip>
  If you use BYOK mode, you do **not** need a FileRouter API key. Instantiate the `FileRouter` class from `@file_router/sdk` (instead of `FileRouterClient`) and supply your provider keys directly, or pass `--local` to the CLI. Your document goes straight to the provider without touching FileRouter's infrastructure.
</Tip>