Skip to main content
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.