# 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](https://orion.file.ai/en/sign-up). 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

Open API Keys

Sign in to the fileAI app as a workspace admin and open **API Keys**.

2

Create the key

Click **Create API Key**. Give it a name, an expiration date and a permission level, then click **Generate API Key**.

3

Copy it now

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

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

Process every element of a file on the path suited to it, and get structured data back.

Next

](/scout/overview)

⌘I

## On this page

*   [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)