> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Auth

> Bill an Agent against a subscription seat instead of an API key.

`auth` tells an Agent to bill a run against a subscription seat rather than an API key.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    A[🤖 new Agent auth] --> R{🔍 provider registered?}
    R -->|no| E[❌ throws at construction]
    R -->|yes| M[🔑 resolve once on first turn]
    M --> F[🌐 wrap fetch with provider headers]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef check fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef err fill:#8B0000,stroke:#7C90A0,color:#fff

    class A agent
    class R check
    class M,F check
    class E err
```

## Quick Start

<Steps>
  <Step title="Pick a provider">
    ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    import { Agent } from 'praisonai';

    const agent = new Agent({
      instructions: 'You are helpful',
      auth: 'claude-code',
    });
    const reply = await agent.chat('Hello');
    ```
  </Step>

  <Step title="Let auth choose the model">
    Omit `llm` and `auth` picks the provider's default model, so a subscription token never ships to the wrong endpoint.
  </Step>
</Steps>

***

## Default models

When you pass `auth` without an `llm`, the agent uses the provider's default model.

| Provider      | Default model                 |
| ------------- | ----------------------------- |
| `claude-code` | `anthropic/claude-sonnet-4-5` |
| `qwen-cli`    | `openai/qwen3-coder-plus`     |

## How it works

The credentials are resolved once on the first turn, then every outgoing request is sent through a `fetch` wrapper that adds the provider's headers. Existing headers on a request win, so you can still override one deliberately.

Because a subscription seat belongs to one vendor, `auth` also pins the default model — falling back to API-key billing would charge the wrong account, so an unregistered provider fails at construction rather than at request time.

## When it throws

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent } from 'praisonai';

new Agent({ instructions: 'Hi', auth: 'not-a-provider' });
// Error: Unknown subscription provider 'not-a-provider'. Registered: (none).
//   A subscription store is a host concern: register one with
//   registerAuthProvider('not-a-provider', resolver).
```

<Note>
  Credential stores (a Claude Code keychain entry, a Codex CLI file) are **host concerns** and are not read by the SDK. Register your own resolver with `registerAuthProvider(name, resolver)` — the TypeScript counterpart to Python's `register_subscription_provider`.
</Note>

## Leaf import for bundle-sensitive callers

`resolveAuth`, `registerAuthProvider`, `listAuthProviders`, `resetAuthProviders`, and the `LLMAuth`, `LLMAuthResolver`, and `LLMAuthSource` types can be imported from `'praisonai'`, `'praisonai/llm'`, or the leaf module `'praisonai/llm/auth'`. All three resolve to the same names — [PraisonAI PR #4874](https://github.com/MervinPraison/PraisonAI/pull/4874) moved the implementation into `llm/auth.ts` and re-exports it, so the public API is unchanged.

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// Any of these work — same names, same behaviour
import { registerAuthProvider } from 'praisonai';
import { registerAuthProvider } from 'praisonai/llm';
import { registerAuthProvider } from 'praisonai/llm/auth';
```

<Tip>
  Prefer `import { … } from 'praisonai'` in application code. The leaf path `'praisonai/llm/auth'` matters only when you build a custom bundle and want auth without pulling in `openai` or the embedding stack — the barrel (`praisonai/llm`) statically imports both.
</Tip>

## Related

<CardGroup cols={2}>
  <Card title="Agent" icon="robot" href="/docs/js/agent">
    Constructor options
  </Card>

  <Card title="Model Routing" icon="route" href="/docs/js/model-routing">
    How model names resolve
  </Card>
</CardGroup>