---
title: "Authentication"
url: "/help/buuk/guides/authentication"
updated: "2026-11-13T13:32:09.431Z"
---
# Authentication

All Buuk API endpoints require HTTPS. Authenticated public routes expect a **Bearer** token in the `Authorization` header: `Authorization: Bearer buuk_cli_…`.

> [!WARNING]
> **Never expose live tokens in client-side code.** Mint tokens in the dashboard and call the API from your server or CI.

## Token roles

- Write tokens can create and update articles (editor-equivalent).
- Read-only tokens can list published docs and analytics; they cannot publish.
- A token cannot exceed the permissions of the member who created it.

## Token lifecycle

- The secret is shown once at creation — copy it immediately
- Revoke compromised tokens from Settings → Developers → API tokens
- Use separate tokens per environment (staging vs production)

## Error responses

Missing or invalid tokens return `401 Unauthorized`:

```json
{
  "error": "unauthorized",
  "message": "Provide an API token via `Authorization: Bearer buuk_cli_…`."
}
```

A read-only token calling a write route returns `403 Forbidden`:

```json
{
  "error": "forbidden",
  "message": "This endpoint requires an editor or owner token."
}
```

> [!DANGER]
> **Write routes are rate-limited (60/min). **Read routes allow 240/min per workspace and IP. Back off on 429.