API Key Management

API keys authenticate all requests to the faktoora API via the X-API-KEY header. This guide covers the full key lifecycle: creation, expiry, rotation, and revocation.

---

Key Status

Every API key has a computed status field returned by GET /apikeys:

Status	Meaning
active	Key is valid and can be used.
expiring_soon	Key expires within 7 days. Rotate before it expires.
expired	expiresAt is in the past. The key is rejected on every request.
revoked	The key has been explicitly revoked. It is rejected on every request and kept for audit purposes.

---

Endpoints

Method	Path	Description
GET	/apikeys	List all API keys for the authenticated user
POST	/apikeys	Create a new API key
PATCH	/apikeys/{apiKeyId}	Update a key's label or expiry date
POST	/apikeys/{apiKeyId}/rotate	Rotate a key (creates a replacement, optionally keeps old key alive during a grace period)
POST	/apikeys/{apiKeyId}/revoke	Immediately revoke a key
DELETE	/apikeys/{apiKeyId}	Permanently delete a key

---

Setting an Expiry Date

You can set an expiry date at creation time (POST /apikeys) or update it later (PATCH /apikeys/{apiKeyId}). The maximum allowed expiry is 365 days from now — the API returns 400 if this limit is exceeded.

PATCH /api/v2/apikeys/ak_abc123
X-API-KEY: <your-key>
Content-Type: application/json

{
  "expiresAt": "2026-12-31T23:59:59Z"
}

Pass "expiresAt": null to remove an existing expiry (key becomes non-expiring).

Once expiresAt is reached, the key stops working immediately — no grace period unless you rotate it first (see below).

---

Rotating a Key

Rotation is the recommended way to replace a key without downtime. It:

1. Creates a new key with a fresh secret.
2. Optionally keeps the old key alive during a configurable grace period so you can update your integrations without a hard cutover.
3. Links the new key back to the old one via rotatedFromId.

POST /api/v2/apikeys/ak_abc123/rotate
X-API-KEY: <your-key>
Content-Type: application/json

{
  "gracePeriodHours": 24,
  "expiresInDays": 365,
  "label": "Production key (rotated)"
}

Request body:

Field	Type	Default	Description
gracePeriodHours	number	24	How long the old key remains usable after rotation. Set to 0 to revoke it immediately.
expiresInDays	number (1–365)	—	Sets expiresAt on the new key (now + expiresInDays). Omit for a non-expiring key.
label	string	—	Label for the new key.

Response: The new key object, including the one-time x-api-key secret. Store it immediately — it cannot be retrieved again.

{
  "apiKeyId": "ak_xyz789",
  "label": "Production key (rotated)",
  "x-api-key": "fk_live_...",
  "expiresAt": "2027-03-14T08:00:00.000Z",
  "rotatedFromId": "ak_abc123",
  "status": "active",
  "createdAt": "2026-03-15T08:00:00.000Z",
  "updatedAt": "2026-03-15T08:00:00.000Z"
}

During the grace period the old key's status will be expiring_soon or expired once the grace window passes. After the grace period ends it is automatically treated as expired.

---

Revoking a Key

Use revocation to immediately block a key — for example if it was leaked or is no longer needed.

POST /api/v2/apikeys/ak_abc123/revoke
X-API-KEY: <your-key>

No request body required. The key is soft-deleted: isRevoked is set to true and revokedAt is recorded. The key remains visible in GET /apikeys for audit purposes but every subsequent request using it receives 401 Unauthorized.

---

Expiry Warning Notifications

faktoora automatically sends email warnings before a key expires:

• 7 days before expiry
• 3 days before expiry
• 1 day before expiry

Warnings are sent to the email address of the user account that owns the key. A maximum of one warning is sent per threshold (2-day cooldown prevents duplicate emails if the cron runs more than once).

To disable expiry warnings for a key, remove its expiresAt date.

---

Best Practices

• Rotate keys on a schedule rather than waiting for them to expire. Use expiresInDays on the new key to enforce a rotation cadence.
• Use gracePeriodHours (24 h is the default) to avoid downtime during rotation — update your environment variables or secrets manager before the grace window closes.
• Revoke immediately when a key is compromised. Rotation is for planned replacements; revocation is for incidents.
• Label your keys with their purpose (e.g. "Production — invoicing service") so you can identify them quickly in the key list.