Auth Integration

AscendKit customers should integrate auth through the SDK, CLI, and portal workflows. The backend /api/auth/* endpoints are implementation details that back those surfaces. They are useful for internal tooling, debugging, and generated internal references, but they are not the primary customer contract.

Customer-facing surfaces

Next.js SDK

Use the JavaScript SDK for sign-in UI, session handling, social login, and route protection.

• Runtime setup: Next.js Integration
• Components: <Login />, <SignUp />, <AscendKitAuthCard />, <AscendKitUserButton />
• Provider config: fetched automatically from AscendKit at runtime

Python SDK

Use the Python package when your backend needs to verify access tokens or validate webhook signatures.

• Token verification: Python SDK
• Webhooks: Python SDK

CLI

Use the CLI to authenticate as a developer, link environments, and configure auth behavior without hand-editing config files. AI coding agents can use the CLI directly via shell commands.

• Setup and login: CLI
• Auth configuration: CLI Auth
• Environment linking: CLI Environments

What customers should rely on

The stable customer contract is:

• SDK constructors, handlers, and components
• CLI commands and their output
• The portal UI
• The docs pages describing those flows

Customers should not build direct integrations against raw backend auth endpoints unless AscendKit explicitly documents that route as externally supported.

Why keep OpenAPI at all

Even if customers do not call backend auth endpoints directly, clean OpenAPI is still useful internally:

• It gives the AscendKit team a precise contract for the SDK and CLI backing APIs.
• It reduces ambiguity when agents inspect backend capabilities during support or debugging.
• It makes breaking changes visible in diffs and tests.
• It supports internal tooling such as typed clients, validation, and smoke checks.

In other words, OpenAPI is an internal source of truth. llms.txt and the docs are the customer-facing explanation layer.

How auth should be documented

For customer-facing docs and llms.txt, the auth story should answer these questions:

• How do I add auth to my app with the SDK?
• How do I configure providers and auth features from the CLI?
• How do I verify tokens in my backend?
• What behavior is automatic versus configurable?

That is more useful to customers than a raw endpoint catalog.

Recommended split

Use this split going forward:

• Customer docs and llms.txt: SDK, CLI, and backend verification examples
• Internal docs and OpenAPI: backing auth endpoints, security headers, schemas, and operational details

This keeps the developer experience aligned with how customers actually adopt AscendKit.