# Authentication for agents

How an agent authenticates to Feeblo's machine surfaces.

- **Product:** Feeblo, an open-source customer feedback platform.
- **Public API base URL:** `https://api.feeblo.com/api/v1`
- **MCP endpoint:** `https://api.feeblo.com/mcp`
- **OpenAPI document:** `https://api.feeblo.com/api/v1/openapi.json`
- **API reference:** `https://api.feeblo.com/api/v1/docs`
- **API guide:** `https://docs.feeblo.com/developers/public-api`
- **MCP guide:** `https://docs.feeblo.com/developers/mcp`

## Do not ask a person for their password

Never ask for a Feeblo account password, session cookie, or better-auth token. The Public API and the MCP server accept exactly one credential: an API key that a workspace admin or owner creates in the Feeblo dashboard.

## Create an API key

A key is owned by one workspace and reads and writes only that workspace's data.

1. Open the Feeblo dashboard for the workspace: `https://app.feeblo.com`.
2. Go to **Settings → Developers**.
3. Create a key and choose the capabilities the integration needs. The key's scopes are fixed at creation and cannot be widened later.
4. Copy the plaintext key. It is shown once and cannot be retrieved again. It starts with `fbk_`.

The Public API is included in the Starter and Professional plans. A workspace on the Free plan cannot create keys. Existing keys survive a downgrade and work again after an upgrade.

## Call the HTTP API

Send the key in the `x-api-key` header:

```sh
curl https://api.feeblo.com/api/v1/boards \
  -H "x-api-key: fbk_..."
```

Every response is JSON. A failure carries a machine-readable `_tag`:

```json
{
  "_tag": "FORBIDDEN_SCOPE",
  "message": "This API key is missing the posts.create scope."
}
```

Statuses: `401` `MISSING_API_KEY` or `INVALID_API_KEY`; `403` `FORBIDDEN_SCOPE` or `PLAN_REQUIRES_UPGRADE`; `404` `NOT_FOUND`; `409` `CONFLICT`; `429` `RATE_LIMITED`; `500` `INTERNAL_ERROR`; `503` `SERVICE_UNAVAILABLE`. Switch on `_tag`, never on `message`.

The per-key budget is 300 requests per minute, shared by reads and writes. A response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`.

## Connect an MCP client

Point a streamable-HTTP MCP client at `https://api.feeblo.com/mcp` and send the same key in the `x-api-key` header. There is no OAuth flow and no separate MCP credential.

Example client configuration:

```json
{
  "mcpServers": {
    "feeblo": {
      "type": "http",
      "url": "https://api.feeblo.com/mcp",
      "headers": {
        "x-api-key": "fbk_..."
      }
    }
  }
}
```

The server supports MCP protocol revisions `2026-07-28`, `2025-11-25`, `2025-06-18`, `2025-03-26`, and `2024-11-05`. Every `/api/v1` operation is one tool. A key that lacks a scope still sees the tool and receives a tool error naming the missing scope when it calls it. Requests carrying an `Origin` header are refused, so a browser client needs a same-origin proxy.

## Read the docs without a key

These are public and need no credential:

- API guide: `https://docs.feeblo.com/developers/public-api`
- MCP guide: `https://docs.feeblo.com/developers/mcp`
- Docs index for agents: `https://docs.feeblo.com/llms.txt`
- Docs MCP server: `https://docs.feeblo.com/mcp`
- API authentication guide (same content, API origin): `https://api.feeblo.com/auth.md`
- API discovery files: `https://api.feeblo.com/.well-known/api-catalog` and `https://api.feeblo.com/.well-known/mcp.json`
- Machine-readable surface manifest: `https://feeblo.com/agent-readability.json`
- Discovery links: `https://feeblo.com/.well-known/api-catalog`

## Ask before writing

Reading is safe. Creating, updating, deleting, merging, publishing, or voting changes a real workspace. Show the person the exact request, the endpoint, and the affected records, then wait for approval before sending it. Publishing a changelog entry emails every subscriber, so treat `changelog.publish` as an announcement, not a save.