Skip to main content

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.

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.