> Markdown version of https://authpi.com/docs/ai/ — fetch the complete AuthPI docs index at https://authpi.com/llms.txt to discover all available pages.

# AuthPI for AI assistants and coding agents

How to consume AuthPI's documentation and integrate AuthPI programmatically — markdown mirrors, llms.txt, machine-readable specs, and a compact integration recipe.

This page is for AI assistants, coding agents, and the humans driving them. Everything below is fetchable without JavaScript.

## Documentation surfaces

- **Index of all pages:** `https://authpi.com/llms.txt` — every docs page with a one-line description and its markdown URL.
- **Full corpus:** `https://authpi.com/llms-full.txt` (~300 KB — fits in a single context window).
- **Markdown mirrors:** append `.md` to any docs page URL (e.g. `/docs/concepts/clients.md`).
- **API reference (markdown, per resource):** `/docs/reference/core-api/<resource>.md` and `/docs/reference/idp-api/<resource>.md` — all listed in llms.txt.
- **Machine-readable specs:** `https://api.authpi.com/openapi.json` (Core API) and `https://idp.authpi.com/openapi.json` (IdP API). OpenAPI 3.1, named component schemas.

## Conventions you can rely on

- **Auth to the Core API:** org API keys over HTTP Basic — `curl -u "$AUTHPI_KEY_ID:$AUTHPI_KEY_SECRET" ...`. Bearer is reserved for JWT access tokens. API keys are issued as an id + secret pair, shown once at creation.
- **Canonical env var names** used across all docs examples: `AUTHPI_KEY_ID`, `AUTHPI_KEY_SECRET`, `AUTHPI_ISSUER_URL`.
- **Resource id prefixes:** `acc_` (account), `i_` (issuer), `c_` (client), `usr_` (user), `org_` (organization), `agt_` (agent), `key_` (API key), `wh_` (webhook), `evt_` (event).
- **Pagination:** list endpoints return `{ data, has_more, next_cursor }` and accept `limit` + `cursor`.
- **Errors:** JSON envelope with `error` and `error_description`; handle rate limiting by status code (`429` + `Retry-After`), not body shape.

## Integration recipe (server-side, any stack)

1. **Get credentials.** A human creates an account at the [AuthPI console](https://console.authpi.com) and issues an org API key (id + secret).
2. **Create an issuer** (your tenant's identity provider): `POST /v1/accounts/{account_id}/issuers` on `api.authpi.com`. The response includes the issuer id (`i_...`); the issuer URL is `https://idp.authpi.com/{issuer_id}`.
3. **Register a client** for your app: `POST .../issuers/{issuer_id}/clients` with `application_type` (`web`, `spa`, `native`, or `m2m`), redirect URIs, and grant types. The secret is returned once.
4. **Authenticate users** with standard OIDC against the issuer URL: discovery at `{issuer_url}/.well-known/openid-configuration`, authorization-code flow with PKCE (S256). Hosted login/signup portals are included — no UI to build.
5. **Validate tokens in your API**: fetch JWKS from discovery, verify signature + `iss` + `aud` + `exp`; cache JWKS for 1 hour and refetch on unknown `kid` (keys rotate monthly with a 45-day overlap).
6. **Verify it works:** `curl {issuer_url}/.well-known/openid-configuration` returns the discovery document; `curl -u "$AUTHPI_KEY_ID:$AUTHPI_KEY_SECRET" https://api.authpi.com/v1/accounts/{account_id}/issuers` lists your issuer.

Framework-specific, single-fetch versions of this recipe (install + env + code + verification):

- Next.js: `/docs/quickstarts/nextjs.md`
- Hono: `/docs/quickstarts/hono.md`
- TypeScript (any server): `/docs/quickstarts/typescript-backend.md`

## SDKs

- IdP (OIDC flows): `@authpi/idp` (npm), `authpi-idp` (PyPI)
- Admin (Core API): `@authpi/admin` (npm), `authpi-admin` (PyPI) — API keys go in as `{ id, secret }` pairs

## Feedback

Found a docs page that contradicts API behavior? That's a bug we fix with priority — open an issue at https://github.com/arbfay/authpi or email contact@authpi.com.