FonProxy API — API Keys

Manage your API keys. All CRUD endpoints require Authorization: Bearer <token> (JWT).

Use API keys for programmatic access. Pass the key via header or query param:

• Header: x-api-key: fnp_...
• Query param: ?apikey=fnp_...

---

Authentication via API Key

Endpoints protected by the API Key guard accept the key in two ways:

# Via header
curl http://localhost:3100/some-endpoint \
  -H "x-api-key: fnp_a1b2c3d4e5f6..."

# Via query param
curl "http://localhost:3100/some-endpoint?apikey=fnp_a1b2c3d4e5f6..."

The API key authenticates as the user who created it. All permissions and roles apply.

---

API Key Management

POST /api-keys

Create a new API key. The raw key is returned ONLY in this response — store it securely.

Headers: Authorization: Bearer <token>

Request body:

{
  "name": "My Script",
  "expiresAt": "2027-01-01T00:00:00.000Z"
}

Field	Type	Required	Description
name	string	yes	Human-readable label for the key
expiresAt	string	no	ISO date — when the key expires. null = never

Response (200):

{
  "apiKey": {
    "id": "k5Xz9qR2Wp",
    "name": "My Script",
    "prefix": "fnp_a1b2",
    "key": "fnp_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12345678",
    "isActive": true,
    "lastAccessAt": null,
    "expiresAt": "2027-01-01T00:00:00.000Z",
    "createdAt": "2026-03-20T10:00:00.000Z"
  },
  "message": "api_key.created"
}

⚠️ The key field is shown only once on creation. It cannot be retrieved later.

---

GET /api-keys

List all API keys for the current user.

Headers: Authorization: Bearer <token>

Response (200):

{
  "apiKeys": [
    {
      "id": "k5Xz9qR2Wp",
      "name": "My Script",
      "prefix": "fnp_a1b2",
      "isActive": true,
      "lastAccessAt": "2026-03-20T14:30:00.000Z",
      "expiresAt": "2027-01-01T00:00:00.000Z",
      "createdAt": "2026-03-20T10:00:00.000Z"
    },
    {
      "id": "mP3aQ7wXvY",
      "name": "CI/CD Pipeline",
      "prefix": "fnp_9f8e",
      "isActive": false,
      "lastAccessAt": "2026-03-19T08:00:00.000Z",
      "expiresAt": null,
      "createdAt": "2026-03-15T12:00:00.000Z"
    }
  ]
}

---

PATCH /api-keys/:id/revoke

Revoke (deactivate) an API key. The key stops working immediately.

Headers: Authorization: Bearer <token>

Response (200):

{ "message": "api_key.revoked" }

Errors:

{ "message": "api_key.not_found" }

---

DELETE /api-keys/:id

Permanently delete an API key.

Headers: Authorization: Bearer <token>

Response (200):

{ "message": "api_key.deleted" }

Errors:

{ "message": "api_key.not_found" }

---

Error format

{
  "message": "api_key.invalid",
  "path": "/some-endpoint",
  "timestamp": "2026-03-20T10:00:00.000Z"
}

Error key	HTTP	Description
api_key.invalid	401	Key is missing, incorrect, revoked, or expired
api_key.not_found	404	Key ID not found or doesn't belong to user
api_key.name_required	400	Name field is empty
api_key.created	200	Key created successfully (not an error)
api_key.revoked	200	Key revoked successfully (not an error)
api_key.deleted	200	Key deleted successfully (not an error)