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.

Generating a PAT

Generate a Personal Access Token at 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.

Reading PAT from the Default Environment Variable

The default environment variable name is QODER_PERSONAL_ACCESS_TOKEN.

export QODER_PERSONAL_ACCESS_TOKEN="<your-qoder-personal-access-token>"

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)

Reading PAT from a Custom Environment Variable

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.

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.

from qoder_agent_sdk import QoderAgentOptions, access_token

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

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.

from qoder_agent_sdk import QoderAgentOptions, qodercli_auth

options = QoderAgentOptions(auth=qodercli_auth())

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.

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.

Errors

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

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.