Authentication & Account¶

Manage API keys, account settings, and usage quotas.

API Key¶

All /v1/ endpoints require authentication via an API key passed in the X-API-Key header:

X-API-Key: fal_xxxxxxxxxxxxxxxxxxxxxxxx

A missing or invalid key returns 401 Unauthorized.

Keep your key secret

Never expose API keys in client-side code or public repositories. Rotate keys immediately if compromised.

API Key Management¶

POST /v1/api-keys¶

Create a new API key for the authenticated account.

Authentication

Header: X-API-Key: your_api_key

Content-Type: application/json Status: 201 Created

Request Body¶

Field	Type	Required	Description
`name`	`string`	yes	Human-readable label for the key (max 100 chars).

{
  "name": "Production Backend"
}

Response (201)¶

{
  "api_key": "fal_xxxxxxxxxxxxxxxxxxxxxxxx",
  "key_hash": "sha256_abc123...",
  "name": "Production Backend",
  "created_at": "2026-03-20T10:00:00+00:00"
}

Save the key immediately

The full API key is only returned once at creation time. It cannot be retrieved later.

Examples¶

cURLPythonJavaScript

curl -X POST https://app.falara.io/v1/api-keys \
  -H "X-API-Key: $FALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Backend"}'

import requests

response = requests.post(
    "https://app.falara.io/v1/api-keys",
    headers={"X-API-Key": FALARA_API_KEY},
    json={"name": "Production Backend"},
)
new_key = response.json()
print(f"Key: {new_key['api_key']}")  # Save this!

const response = await fetch("https://app.falara.io/v1/api-keys", {
  method: "POST",
  headers: {
    "X-API-Key": FALARA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Production Backend" }),
});
const newKey = await response.json();
console.log(`Key: ${newKey.api_key}`); // Save this!

Errors¶

Status	Description
`401`	Invalid or missing API key.
`403`	Plan does not allow API key creation (Free plan), or key limit reached.

GET /v1/api-keys¶

List all API keys for the authenticated account. The key value itself is not returned -- only the hash and metadata.

Authentication

Header: X-API-Key: your_api_key

Status: 200 OK

Response (200)¶

[
  {
    "key_hash": "sha256_abc123...",
    "name": "Production Backend",
    "created_at": "2026-03-20T10:00:00+00:00"
  },
  {
    "key_hash": "sha256_def456...",
    "name": "Staging",
    "created_at": "2026-03-18T09:00:00+00:00"
  }
]

Examples¶

cURLPythonJavaScript

curl -X GET https://app.falara.io/v1/api-keys \
  -H "X-API-Key: $FALARA_API_KEY"

import requests

response = requests.get(
    "https://app.falara.io/v1/api-keys",
    headers={"X-API-Key": FALARA_API_KEY},
)
keys = response.json()
for key in keys:
    print(f"{key['name']} ({key['key_hash'][:16]}...)")

const response = await fetch("https://app.falara.io/v1/api-keys", {
  headers: { "X-API-Key": FALARA_API_KEY },
});
const keys = await response.json();
keys.forEach((k) => console.log(`${k.name} (${k.key_hash.slice(0, 16)}...)`));

DELETE /v1/api-keys/{key_hash}¶

Revoke an API key. The key will immediately stop working.

Authentication

Header: X-API-Key: your_api_key

Status: 204 No Content

Examples¶

cURLPythonJavaScript

curl -X DELETE "https://app.falara.io/v1/api-keys/sha256_abc123..." \
  -H "X-API-Key: $FALARA_API_KEY"

import requests

response = requests.delete(
    f"https://app.falara.io/v1/api-keys/{key_hash}",
    headers={"X-API-Key": FALARA_API_KEY},
)
assert response.status_code == 204

const response = await fetch(
  `https://app.falara.io/v1/api-keys/${keyHash}`,
  {
    method: "DELETE",
    headers: { "X-API-Key": FALARA_API_KEY },
  }
);
console.log(response.status); // 204

Errors¶

Status	Description
`401`	Invalid or missing API key.
`404`	Key hash not found.

Account Management¶

GET /v1/account¶

Get the account linked to the authenticated API key.

Authentication

Header: X-API-Key: your_api_key

Status: 200 OK

Response (200)¶

{
  "account_id": "acc-uuid-1",
  "account_name": "Eurotext GmbH",
  "plan": "professional",
  "role": "owner"
}

Field	Type	Description
`account_id`	`string`	Unique account identifier.
`account_name`	`string`	Display name of the account.
`plan`	`string`	Current plan (`free`, `starter`, `professional`, `business`, `enterprise`).
`role`	`string`	Caller's role within the account (`owner` or `member`).

PATCH /v1/account¶

Update the account name. Only the account owner may rename the account.

Authentication

Header: X-API-Key: your_api_key

Content-Type: application/json Status: 200 OK

Request Body¶

Field	Type	Required	Description
`account_name`	`string`	yes	New account name (1--100 characters).

{
  "account_name": "Eurotext International"
}

Response (200)¶

{
  "account_id": "acc-uuid-1",
  "account_name": "Eurotext International",
  "plan": "professional",
  "role": "owner"
}

Errors¶

Status	Description
`401`	Invalid or missing API key.
`403`	Only the account owner can rename the account.

GET /v1/account/usage¶

Get the current word quota usage for the billing period.

Authentication

Header: X-API-Key: your_api_key

Status: 200 OK

Response (200)¶

{
  "plan": "professional",
  "period_start": "2026-03-01T00:00:00+00:00",
  "period_end": "2026-03-31T23:59:59+00:00",
  "words_used": 42500,
  "words_limit": 100000,
  "words_remaining": 57500
}

Field	Type	Description
`plan`	`string`	Current plan name.
`period_start`	`string`	ISO 8601 start of the current billing period.
`period_end`	`string`	ISO 8601 end of the current billing period.
`words_used`	`integer`	Billed words consumed so far this period.
`words_limit`	`integer`	Total word quota for the period.
`words_remaining`	`integer`	Words remaining (`words_limit - words_used`).

Examples¶

cURLPythonJavaScript

curl -X GET https://app.falara.io/v1/account/usage \
  -H "X-API-Key: $FALARA_API_KEY"

import requests

response = requests.get(
    "https://app.falara.io/v1/account/usage",
    headers={"X-API-Key": FALARA_API_KEY},
)
usage = response.json()
print(f"Used: {usage['words_used']} / {usage['words_limit']}")

const response = await fetch("https://app.falara.io/v1/account/usage", {
  headers: { "X-API-Key": FALARA_API_KEY },
});
const usage = await response.json();
console.log(`Used: ${usage.words_used} / ${usage.words_limit}`);

Errors¶

Status	Description
`401`	Invalid or missing API key.

DELETE /v1/account/data¶

Request deletion of all account data (GDPR Art. 17). This permanently deletes all jobs, glossaries, files, and account information.

Authentication

Header: X-API-Key: your_api_key

This action is irreversible

All data associated with the account will be permanently deleted. API keys will be revoked. This cannot be undone.

Status: 200 OK

Response (200)¶

{
  "deleted_jobs": 142,
  "deleted_glossaries": 5,
  "deleted_api_key": 3
}

Examples¶

cURLPythonJavaScript

curl -X DELETE https://app.falara.io/v1/account/data \
  -H "X-API-Key: $FALARA_API_KEY"

import requests

response = requests.delete(
    "https://app.falara.io/v1/account/data",
    headers={"X-API-Key": FALARA_API_KEY},
)
result = response.json()
print(f"Deleted {result['deleted_jobs']} jobs, {result['deleted_glossaries']} glossaries")

const response = await fetch("https://app.falara.io/v1/account/data", {
  method: "DELETE",
  headers: { "X-API-Key": FALARA_API_KEY },
});
const result = await response.json();
console.log(`Deleted ${result.deleted_jobs} jobs, ${result.deleted_glossaries} glossaries`);

Errors¶

Status	Description
`401`	Invalid or missing API key.

Plan Limits¶

Feature availability and quotas depend on your plan:

Plan	API Keys	Words/Month	Premium Quality	Google Drive
Free	--	10,000	--	--
Starter	3	50,000	:white_check_mark:	--
Professional	3	100,000	:white_check_mark:	:white_check_mark:
Business	10	500,000	:white_check_mark:	:white_check_mark:
Enterprise	Unlimited	Unlimited	:white_check_mark:	:white_check_mark:

Upgrading

Switch plans via the Dashboard or PATCH /v1/account/plan. Changes take effect immediately and quotas are adjusted for the current period.

Rate Limiting¶

API requests are rate-limited per API key. When you exceed the limit, the API returns 429 Too Many Requests.

Limit	Value
Requests per minute	50
Concurrent jobs	50

Handling rate limits

When you receive a 429 response, back off and retry after the period indicated by the Retry-After header (if present). Implement exponential backoff for production integrations.

Security Best Practices¶

Rotate keys regularly. Create a new key, update your integrations, then revoke the old one.
Use separate keys for production and development environments.
Never commit keys to version control. Use environment variables or secret managers.
Monitor usage via GET /v1/account/usage to detect unexpected consumption.
Set up webhooks to receive real-time notifications instead of polling.

Errors¶

All authentication errors return a JSON body:

{
  "detail": "A human-readable description of the error."
}

Status	Description
`401`	Missing or invalid API key.
`403`	Insufficient plan for the requested feature, or insufficient role for the operation.
`429`	Rate limit exceeded.