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 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 a nested body — { "name", "type", "confidential", "settings": { "protocol": "oidc", "scopes": [...], "openid": { "application_type", "grant_types", "redirect_uris" } } }, where application_type is web, spa, native, or m2m. 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.