# Docs for agents

> llms.txt, markdown copies of every page, the OpenAPI spec and a prompt for coding agents.

Coding agents read these docs as well as people do, and often more of
them. Everything on this site is available in a form an agent can fetch
and read without rendering a page.

## What to point an agent at

| URL | What |
|---|---|
| [`/llms.txt`](https://authbase.burakmetehan.com.tr/llms.txt) | An index of every page with a one-line summary ([llmstxt.org](https://llmstxt.org)). Start here. |
| [`/llms-full.txt`](https://authbase.burakmetehan.com.tr/llms-full.txt) | Every page in one file, for agents that prefer one fetch. |
| `/docs/<page>.md` | Each page as plain markdown: add `.md` to a page's path, e.g. [`/docs/integration.md`](https://authbase.burakmetehan.com.tr/docs/integration.md). |
| [`/openapi.yaml`](https://authbase.burakmetehan.com.tr/openapi.yaml) | The OpenAPI 3.0 spec: every endpoint, request and response body, and error code. |

The markdown copies are generated from the same files as the pages you
are reading, so they never disagree.

## With Claude

The [Claude skills](https://authbase.burakmetehan.com.tr/docs/skills.md) come with the first public release.
Once installed, Claude follows authbase's rules on its own (API key only
in the environment, tokens verified locally, refresh tokens out of
JavaScript, the error codes to branch on) and checks its work with the
skill's `verify-flow.sh` against your instance.

## With any other agent

Give it the docs and the rules in the prompt. A starting point:

```text
Add authentication to this backend with authbase, a self-hosted auth
service. Read https://authbase.burakmetehan.com.tr/llms.txt and the pages
it links to before writing code: at least the integration guide and the
SDK page for this stack.

The instance is in AUTHBASE_URL and the app's API key in AUTHBASE_API_KEY.
Both are already in the environment; never write the key into code, a
committed file, a log line or your reply.

Rules:
- Sign-up, login, refresh and logout go from this backend to authbase.
  Pass the end-user's IP as client_ip.
- Verify access tokens locally against the app's JWKS (EdDSA only,
  typ at+jwt, issuer, audience = app id, expiry). Never call authbase per
  request, and never decode a token without verifying it.
- Browser clients get the refresh token in an HttpOnly, Secure, SameSite
  cookie, never in localStorage.
- Branch on the error `code` in authbase's problem+json responses.
```

## Keeping agents honest

Two things catch an integration that only looks right:

- **The error codes are the contract.** The [integration guide's table](https://authbase.burakmetehan.com.tr/docs/integration.md#4-errors-you-will-see)
  and the [API reference](https://authbase.burakmetehan.com.tr/api/) list them; an agent should branch on
  `code`, not on message text.
- **Run the flow end to end.** The integrate skill's `verify-flow.sh`
  signs a user up through your backend, checks a protected route and a
  role-only route, tries a wrong password, refreshes, replays a spent
  refresh token and logs out, checking every answer.