# Feeblo auth.md

The authentication guide for agents reaching this origin. Feeblo's machine
surfaces accept exactly one credential: a workspace API key.
Never ask a person for a password, a session cookie, or a better-auth token.

## Create a key

1. Open the 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 scopes
   are fixed at creation and cannot be widened later.
4. Copy the plaintext key. It is shown once, starts with `fbk_`, and cannot be
   retrieved again.

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

## Call the API

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

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

A failure carries a machine-readable `_tag`:

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

| Status | `_tag` | Meaning |
| --- | --- | --- |
| 401 | `MISSING_API_KEY` | No `x-api-key` header, or an empty one. |
| 401 | `INVALID_API_KEY` | Unknown, revoked, expired, or disabled key. |
| 403 | `FORBIDDEN_SCOPE` | The key lacks the scope the endpoint requires. |
| 403 | `PLAN_REQUIRES_UPGRADE` | The workspace plan does not include the Public API. |
| 404 | `NOT_FOUND` | The record does not exist in this workspace. |
| 409 | `CONFLICT` | The write conflicts with the current state. |
| 429 | `RATE_LIMITED` | The per-key budget is exhausted; read `Retry-After`. |
| 500 | `INTERNAL_ERROR` | Unexpected server failure. |
| 503 | `SERVICE_UNAVAILABLE` | A required dependency is unavailable; requests fail closed. |

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

## Connect an MCP client

Use the same key. There is no OAuth flow and no separate MCP credential.

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

Supported protocol revisions: `2026-07-28`, `2025-11-25`, `2025-06-18`,
`2025-03-26`, and `2024-11-05`. Requests carrying an `Origin` header are
refused, so a browser client needs a same-origin proxy.

## Read without a key

- API reference: https://api.feeblo.com/api/v1/docs
- OpenAPI document: https://api.feeblo.com/api/v1/openapi.json
- Public API guide: https://docs.feeblo.com/developers/public-api
- MCP guide: https://docs.feeblo.com/developers/mcp
- Documentation index: https://docs.feeblo.com/llms.txt
- Machine-readable surfaces: https://feeblo.com/agent-readability.json

## Ask before writing

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