# Authentication and regions
Source: https://docs.file.ai/authentication

> Create an API key, pick the base URL for your region, and follow the conventions every request shares.

Get started

# Authentication and regions

Copy pageCopy page

Create an API key, pick the base URL for your region, and follow the conventions every request shares.

Copy pageCopy page

Every fileAI API request carries an API key in the `x-api-key` header and goes to the host of the instance your workspace lives on. The API is REST over HTTPS, with the same paths, methods and bodies on every instance.

## 

[​

](#before-you-start)

Before you start

You need:

*   **A fileAI account.** [Sign up or sign in on the Developer Portal](https://developer.file.ai). Already use the fileAI app at orion.file.ai? The same sign-in works on both, so you can move between them without signing in again. Self-serve and enterprise accounts both work.
*   **An API key.** Only workspace admins can create one (see below).
*   **An approved AI Schema** (Verify in the app) if you want structured values back. fileAI suggests schemas as files arrive; confirm or edit them in the app. See [AI Schemas](/extract/ai-schemas) and [Concepts](/concepts).

## 

[​

](#create-an-api-key)

Create an API key

1

Choose your project

Sign in to the [Developer Portal](https://developer.file.ai) as a workspace admin, then pick the organization and project from the switcher at the top.

2

Create the key

Open **API Keys** in the sidebar and click **Create API Key**. Fill in the form, then click **Generate token**:

*   **Name**: anything that tells you where the key is used.
*   **Expiration**: 7, 30, 60 or 90 days, or Never.
*   **Permissions**: **Read only** (fetch data, but not change it) or **Full Access** (read and change data).

A project key works for both fileScout and fileForensics.

3

Copy it now

The key is shown once. Copy it and store it in a secret manager or environment variable.

The Developer Portal works with Developer Portal workspaces. If your workspace was set up in the fileAI app, create keys in the app instead: **Settings → API Keys** at [orion.file.ai](https://orion.file.ai).

Treat the key like a password. Never commit it to source control or ship it in client-side code. Anyone holding it can act on your workspace.

### 

[​

](#key-types)

Key types

There are two kinds of key. Both work on one instance only.

Key

Reaches

Project on each request

**Project key**

One project.

Not needed. The key’s own project is used and any `x-project-id` header is ignored.

**Personal key**

Several projects, across the workspaces the key covers. MCP clients use these.

Required: send the project id in an **`x-project-id`** header. Without it the request returns `400`; a project you can’t open returns `403`.

Personal keys cannot call `PATCH /v1/project/setting`, which needs a project admin. See [Concepts](/concepts) for how workspaces, projects and folders relate.

### 

[​

](#what-a-key-can-do)

What a key can do

Key state

What happens

Read-only

`GET` requests only. Any other method returns `403` with code `READONLY_KEY`.

Inactive

Every request returns `403` (`API key is inactive.`).

Missing or unknown

`401` (`API key is missing` or `Invalid API key.`).

## 

[​

](#authenticate-a-request)

Authenticate a request

Send the key in the `x-api-key` header:

cURL

Python

Node.js

```
curl "https://api.orion.file.ai/prod/v1/health-check" \
  -H "x-api-key: $FILEAI_API_KEY"
```

```
import os, requests

r = requests.get(
    "https://api.orion.file.ai/prod/v1/health-check",
    headers={"x-api-key": os.environ["FILEAI_API_KEY"]},
)
print(r.json())
```

```
const r = await fetch("https://api.orion.file.ai/prod/v1/health-check", {
  headers: { "x-api-key": process.env.FILEAI_API_KEY },
});
console.log(await r.json());
```

Response

```
{ "message": "Public API is up and running!" }
```

### 

[​

](#try-requests-in-the-docs)

Try requests in the docs

Every endpoint page in the **API reference** tab has a playground. Enter your key, pick your region from the server dropdown, and send the request. The code samples update to match, so you can copy a snippet that already points at the right host.

## 

[​

](#regions)

Regions

fileAI runs separate instances. Each serves exactly the same API and differs only in the hostname.

Instance

Region

Base URL

App

Default

Hosted in the US

`https://api.orion.file.ai/prod/v1`

[orion.file.ai](https://orion.file.ai)

`au`

Australia

`https://api.orion.au.file.ai/prod/v1`

[orion.au.file.ai](https://orion.au.file.ai)

`sg`

Singapore

`https://api.orion.sg.file.ai/prod/v1`

[orion.sg.file.ai](https://orion.sg.file.ai)

`jp`

Japan

`https://api.orion.jp.file.ai/prod/v1`

[orion.jp.file.ai](https://orion.jp.file.ai)

Use the default unless you have been told otherwise. Every example in these docs uses it. Not sure which instance your workspace is on? Ask your account manager or [support@file.ai](mailto:support@file.ai).

A workspace belongs to exactly one instance, and a key only authenticates on the host that issued it. A request to another instance fails authentication even though the endpoint exists there. Switch the base URL and the key together.

### 

[​

](#switching-between-instances)

Switching between instances

Only the hostname changes, so switching never means rewriting a request. Keep the host in one variable and build every path from it:

```
# Default
export FILEAI_BASE_URL="https://api.orion.file.ai/prod/v1"

# Singapore
export FILEAI_BASE_URL="https://api.orion.sg.file.ai/prod/v1"

curl "$FILEAI_BASE_URL/files" -H "x-api-key: $FILEAI_API_KEY"
```

Every guide sets **`FILEAI_BASE_URL` to `…/prod/v1`** and appends the endpoint path, for example `$FILEAI_BASE_URL/files/upload`. In Python and Node the guides use `BASE = "https://api.orion.file.ai/prod/v1"` the same way. In a one-off cURL command, replace the host and leave the path, query string, headers and body as they are:

```
# Default
curl "https://api.orion.file.ai/prod/v1/files" -H "x-api-key: $FILEAI_API_KEY"

# Same call, Japan instance
curl "https://api.orion.jp.file.ai/prod/v1/files" -H "x-api-key: $FILEAI_API_KEY"
```

## 

[​

](#request-conventions)

Request conventions

Convention

Detail

Methods

`GET`, `POST`, `PATCH` and `DELETE`.

Request bodies

JSON (`Content-Type: application/json`) for every endpoint except `POST /v1/extract`, `POST /v1/split`, `POST /v1/classify` and `POST /v1/files/schema/import`. Those take `multipart/form-data`; the extract, split and classify endpoints take the document in a `file` field, up to 50 MB.

Project

Personal keys send `x-project-id` on each request. See [Key types](#key-types).

File uploads

Files go straight to storage through a presigned URL, not through the API. See [Uploads](/ingest/uploads).

Request ids

Every response carries an `X-Request-Id` header. Quote it when you contact support. See [Request ids](/api/errors#request-ids).

Errors

RFC 9457 problem documents with a stable `code`. See [Errors](/api/errors).

Retries

Send an `Idempotency-Key` header on JSON writes to make retries safe. Multipart endpoints ignore it. See [Idempotency](/api/idempotency).

Rate limits

Requests over your limit return `429`. See [Rate limits](/api/rate-limits).

Pagination

List endpoints page their results. See [Pagination](/api/pagination).

## 

[​

](#related)

Related

## API quickstart

Upload a file and read its values in about 5 minutes.

## Errors

Status codes, problem documents and error codes.

## Idempotency

Retry writes without applying them twice.

## Workspace setup

Invite your team and manage roles.

[Previous](/quickstart/app)[

Overview

Read every element of a file the way that suits it, and get structured data back.

Next

](/scout/overview)

⌘I

## On this page

Back to top

*   [Before you start](#before-you-start)
*   [Create an API key](#create-an-api-key)
    *   [Key types](#key-types)
    *   [What a key can do](#what-a-key-can-do)
*   [Authenticate a request](#authenticate-a-request)
    *   [Try requests in the docs](#try-requests-in-the-docs)
*   [Regions](#regions)
    *   [Switching between instances](#switching-between-instances)
*   [Request conventions](#request-conventions)
*   [Related](#related)