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

# SDK Authentication

`query()` and `QoderSDKClient` require authentication configuration when launching `qodercli` through the SDK. The recommended approach for scripts, CI, and host applications is a Personal Access Token (PAT) injected via environment variables.

If you have already logged in locally via `qodercli`, you can also reuse the existing credentials.

<div id="generating-a-pat" />

<div id="generatingapat" />

## Generating a PAT

Generate a Personal Access Token at [qoder.com/account/integrations](https://qoder.com/account/integrations):

1. Sign in to your Qoder account
2. Open **Account → Integrations**
3. Create a new PAT, picking expiry and scopes as needed
4. **Copy it immediately** — the value cannot be retrieved again after the page is closed; if lost, you must regenerate

> A single account can hold multiple PATs. Issuing separate tokens per environment (local scripts, CI, production) makes per-token revocation possible.

<div id="reading-pat-from-the-default-environment-variable" />

<div id="readingpatfromthedefaultenvironmentvariable" />

## Reading PAT from the Default Environment Variable

The default environment variable name is `QODER_PERSONAL_ACCESS_TOKEN`.

```bash theme={null}
export QODER_PERSONAL_ACCESS_TOKEN="<your-qoder-personal-access-token>"
```

```python theme={null}
from qoder_agent_sdk import QoderAgentOptions, access_token_from_env, query

options = QoderAgentOptions(auth=access_token_from_env())

async for message in query(
    prompt="Summarize the purpose of this project in one sentence.",
    options=options,
):
    print(message)
```

<div id="reading-pat-from-a-custom-environment-variable" />

<div id="readingpatfromacustomenvironmentvariable" />

## Reading PAT from a Custom Environment Variable

```python theme={null}
from qoder_agent_sdk import QoderAgentOptions, access_token_from_env

options = QoderAgentOptions(auth=access_token_from_env("MY_QODER_PAT"))
```

If the same-named variable is set in both `options.env` and the process environment, the SDK reads the value from `options.env` first.

<div id="passing-the-pat-directly" />

<div id="passingthepatdirectly" />

## Passing the PAT Directly

If your host application has already obtained a PAT from a secrets management service, existing credentials, or a backend API, you can pass it directly. Do not hard-code token literals in source code.

```python theme={null}
from qoder_agent_sdk import QoderAgentOptions, access_token

token = read_token_from_secret_manager()
options = QoderAgentOptions(auth=access_token(token))
```

<div id="reusing-qodercli-login-session" />

<div id="reusingqodercliloginsession" />

## Reusing qodercli Login Session

If you have already completed login locally via `qodercli`, you can let the SDK delegate to the CLI to read the existing credentials.

```python theme={null}
from qoder_agent_sdk import QoderAgentOptions, qodercli_auth

options = QoderAgentOptions(auth=qodercli_auth())
```

<div id="authentication-failure-callback" />

<div id="authenticationfailurecallback" />

## Authentication Failure Callback

When the remote rejects the token, the token expires, or the CLI exits with an auth error, use `on_auth_expired` to trigger a re-login or token refresh flow. It fires at most once per SDK session.

```python theme={null}
from qoder_agent_sdk import QoderAgentOptions, access_token_from_env

def show_sign_in_required() -> None:
    print("Authentication has expired. Please sign in again.")

options = QoderAgentOptions(
    auth=access_token_from_env(),
    on_auth_expired=show_sign_in_required,
)
```

The SDK does not automatically refresh PATs. After obtaining a new token, create a new session with the new `auth` configuration.

<div id="errors" />

## Errors

* Missing auth configuration: `AuthNotConfiguredError`, `code == "auth_not_configured"`.
* Environment variable not set: `AuthAccessTokenEnvVarError`, `code == "auth_access_token_env_var_not_configured"`.

<div id="best-practices" />

<div id="bestpractices" />

## Best Practices

* In production and CI, prefer environment variables or secrets management services; never hard-code tokens.
* Do not write tokens to logs, error objects, or test snapshots.
* For automated environments, prefer PATs over relying on the local `qodercli` login session.
* For user-facing applications, register `on_auth_expired` to convert authentication failures into clear sign-in prompts.