Authentication

The Fenicia API uses API keys to authenticate every request. Keys identify your account (tenant), define the available permissions, and are sent in the Authorization header using the Bearer scheme.

Before you start, you'll need to generate an API key from the Fenicia dashboard. This guide walks you through the full process step by step.

Base URL

https://api.fenicia.io

Single domain

All Fenicia API endpoints live under api.fenicia.io. The accounts.fenicia.io domain is used only for the dashboard's auth flow, and webhooks.fenicia.io for receiving third-party webhooks — neither is used to consume the public API.

Getting an API Key

Follow these steps from your Fenicia dashboard to generate a new API key.

Sign in to your Fenicia dashboard

Open app.fenicia.io in your browser and sign in with your email and password. If you have two-factor authentication enabled, enter the code as well.

Open Settings

In the left sidebar, click Settings. This is the gear icon near the bottom of the main menu.

Go to API Keys

Inside the Settings submenu, select API Keys. You'll see the list of existing keys (or an empty state if this is your first time).

Create a new key

Click the + Create API key button in the top-right corner of the screen.

Configure the key

Fill in the form with the details for the new key:

Name: descriptive, for example Production - My integration or Staging - Import script.
Expiration date (optional): recommended for production environments. If you leave it blank, the key never expires.
Scopes: select only the permissions your integration needs (e.g. orders:read, products:update). Apply the principle of least privilege.

Copy the key IMMEDIATELY

Shown only once

For security reasons, Fenicia only displays the full key at creation time. Once you close the modal, you cannot retrieve it. If you lose it, you'll need to create a new one and update your integration.

Copy the key and store it in a safe place: a password manager (1Password, Bitwarden), a secrets manager (AWS Secrets Manager, HashiCorp Vault), or an environment variable on your server.

Save the key in your environment

Never hardcode the API key into your source code. The recommended practice is to read it from an environment variable:

# .env
FENICIA_API_KEY=fn_live_your_api_key_here

Make sure your .env file is listed in .gitignore so it never ends up in your repository.

API Keys section under Settings, with the Create API key button in the top-right corner — Settings → API Keys. This is where you manage every API key for your account.

Key formats

Fenicia API keys have one of the following prefixes depending on their origin:

Prefix	Usage
`fn_live_...`	Production environment (current format)
`fkapi_...`	Legacy keys (still supported, will be migrated to `fn_live_` in the future)

Security

Treat API keys like passwords

Never expose API keys in client-side code, public repositories, logs, screenshots, or support tickets. If you suspect a key has been leaked, revoke it immediately and generate a new one.

Making authenticated requests

Include your API key in the Authorization header of every request:

Authorization: Bearer fn_live_your_api_key_here

Examples per language

curl https://api.fenicia.io/orders \
  -H "Authorization: Bearer fn_live_your_api_key" \
  -H "Content-Type: application/json"

Scopes (Permissions)

Every API key has a set of scopes that define which resources it can access. The format is resource:action.

Scope	Grants
`orders:read`	List and retrieve orders
`orders:create`	Create manual orders
`orders:update`	Modify existing orders
`orders:*`	All actions on orders
`products:read`	Read the product catalog
`inventory:update`	Adjust stock levels
`:`	Full access (owners only)

If you call an endpoint without the required scope, you'll receive a 403 INSUFFICIENT_PERMISSIONS error.

Rate Limiting

The API is rate-limited to 100 requests per 60 seconds per IP. If you exceed the limit, you'll receive a 429 Too Many Requests:

{
  "error": "Too many requests",
  "retryAfter": 45
}

Tip

Implement retries with exponential backoff, respecting the retryAfter value (in seconds).

Rotating or revoking a key

Rotating API keys periodically (every 60-90 days) is a good security practice. Fenicia lets you rotate without downtime if you follow this process.

Rotate a key with zero downtime

Create a new API key

From Settings → API Keys, create a new key with the same scopes as the current one. Give it a name that identifies the rotation cycle (for example Production - 2026-Q2).

Update your application

Roll out the new environment variable value (FENICIA_API_KEY) to all your servers or functions. Verify that requests succeed with the new key.

Revoke the old key

Once you've confirmed that all traffic is using the new key, revoke the old one from the API Keys list.

Revoke a key

In the API Keys list, click the delete icon next to the key you want to revoke and confirm the action.

Takes effect immediately

Revoked keys stop working right away: any request using them will receive 401 INVALID_API_KEY. Make sure you've migrated all traffic before revoking.

Authentication errors

Code	Status	Description
`MISSING_AUTHORIZATION`	401	The `Authorization` header was not sent
`INVALID_AUTHORIZATION_FORMAT`	401	Header doesn't follow `Bearer <key>` format
`INVALID_API_KEY`	401	API key doesn't exist, is expired, or revoked
`INSUFFICIENT_PERMISSIONS`	403	Key lacks the required scope for this endpoint
`account/billing_restricted`	403	Account is suspended due to billing issues

Next steps

Authentication

Before you start, you'll need to generate an API key from the Fenicia dashboard. This guide walks you through the full process step by step.

Getting an API Key

Follow these steps from your Fenicia dashboard to generate a new API key.

Sign in to your Fenicia dashboard

Open app.fenicia.io in your browser and sign in with your email and password. If you have two-factor authentication enabled, enter the code as well.

Open Settings

In the left sidebar, click Settings. This is the gear icon near the bottom of the main menu.

Go to API Keys

Inside the Settings submenu, select API Keys. You'll see the list of existing keys (or an empty state if this is your first time).

Create a new key

Click the + Create API key button in the top-right corner of the screen.

Configure the key

Fill in the form with the details for the new key:

Name: descriptive, for example Production - My integration or Staging - Import script.
Expiration date (optional): recommended for production environments. If you leave it blank, the key never expires.
Scopes: select only the permissions your integration needs (e.g. orders:read, products:update). Apply the principle of least privilege.

Copy the key IMMEDIATELY

Shown only once

Copy the key and store it in a safe place: a password manager (1Password, Bitwarden), a secrets manager (AWS Secrets Manager, HashiCorp Vault), or an environment variable on your server.

Save the key in your environment

Never hardcode the API key into your source code. The recommended practice is to read it from an environment variable:

# .env
FENICIA_API_KEY=fn_live_your_api_key_here

Make sure your .env file is listed in .gitignore so it never ends up in your repository.

Settings → API Keys. This is where you manage every API key for your account.

Prefix

Usage

fn_live_...

Production environment (current format)

fkapi_...

Legacy keys (still supported, will be migrated to fn_live_ in the future)

Scopes (Permissions)

Every API key has a set of scopes that define which resources it can access. The format is resource:action.

Scope

Grants

orders:read

List and retrieve orders

orders:create

Create manual orders

orders:update

Modify existing orders

orders:*

All actions on orders

products:read

Read the product catalog

inventory:update

Adjust stock levels

*:*

Full access (owners only)

If you call an endpoint without the required scope, you'll receive a 403 INSUFFICIENT_PERMISSIONS error.

Rotating or revoking a key

Rotating API keys periodically (every 60-90 days) is a good security practice. Fenicia lets you rotate without downtime if you follow this process.

Create a new API key

From Settings → API Keys, create a new key with the same scopes as the current one. Give it a name that identifies the rotation cycle (for example Production - 2026-Q2).

Update your application

Roll out the new environment variable value (FENICIA_API_KEY) to all your servers or functions. Verify that requests succeed with the new key.

Revoke the old key

Once you've confirmed that all traffic is using the new key, revoke the old one from the API Keys list.

In the API Keys list, click the delete icon next to the key you want to revoke and confirm the action.

Takes effect immediately

Revoked keys stop working right away: any request using them will receive 401 INVALID_API_KEY. Make sure you've migrated all traffic before revoking.

Authentication errors

Code

Status

Description

MISSING_AUTHORIZATION

401

The Authorization header was not sent

INVALID_AUTHORIZATION_FORMAT

401

Header doesn't follow Bearer <key> format

INVALID_API_KEY

401

API key doesn't exist, is expired, or revoked

INSUFFICIENT_PERMISSIONS

403

Key lacks the required scope for this endpoint

account/billing_restricted

403

Account is suspended due to billing issues