SDK Authentication

​

Use a PAT

​

Get a PAT

1. Sign in to Qoder.
2. Open Account → Integrations.
3. Choose the required permissions and expiry, then create the PAT.
4. Copy the generated value immediately. It cannot be viewed again after the page is closed.

​

Read a PAT from the environment

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

import { accessTokenFromEnv, query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: 'Summarize the current workspace.',
  options: {
    auth: accessTokenFromEnv(),
  },
});

auth: accessTokenFromEnv('MY_QODER_PAT')

​

Pass a PAT directly

import { accessToken, query } from '@qoder-ai/qoder-agent-sdk';

const token = await readTokenFromSecretManager();
const q = query({
  prompt: 'List the most recently modified files.',
  options: {
    auth: accessToken(token),
  },
});

​

Use a Service Account

​

Pass a Service Account key directly

import { query, serviceAccount } from '@qoder-ai/qoder-agent-sdk';

// Get the Service Account key from the host's secret manager adapter.
const serviceAccountKey = await readSecret('qoder-service-account-key');

const q = query({
  prompt: 'Explain the purpose of this project in one sentence.',
  options: {
    auth: serviceAccount({ serviceAccountKey }),
    cwd: process.cwd(),
  },
});

secret manager
     |
     | Service Account Key
     v
caller reads the key
     |
     | serviceAccount({ serviceAccountKey })
     v
SDK starts qodercli and obtains a short-lived SAT
     |
     `----> authenticate session requests with the SAT

​

Provide and refresh SATs from the host

qodercli
     |
     | request a SAT
     v
fetchServiceAccountToken callback in the SDK host
     |
     | call Token exchange with the host-managed Service Account key
     v
Qoder Token exchange
     |
     `----> return the short-lived SAT to qodercli

import {
  query,
  serviceAccount,
  type ServiceAccountTokenResult,
} from '@qoder-ai/qoder-agent-sdk';

// Get the Service Account key from the host's secret manager adapter.
const serviceAccountKey = await readSecret('qoder-service-account-key');
// Example: select the scopes used for model listing and inference.
const serviceAccountScopes = ['models.read', 'chat.completions'];

async function fetchServiceAccountToken(): Promise<ServiceAccountTokenResult> {
  const response = await fetch(
    'https://openapi.qoder.sh/api/v1/serviceToken/exchange',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${serviceAccountKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        grant_type: 'client_credentials',
        audience: 'qoder',
        scope: serviceAccountScopes.join(' '),
        ttl_seconds: 3600,
      }),
    },
  );

  if (!response.ok) {
    throw new Error(`Unable to obtain a Qoder SAT: HTTP ${response.status}`);
  }

  const result = (await response.json()) as {
    access_token: string;
    expires_in?: number;
  };

  return {
    token: result.access_token,
    expiresAt:
      result.expires_in === undefined
        ? undefined
        : Date.now() + result.expires_in * 1000,
  };
}

const q = query({
  prompt: 'Summarize the current deployment configuration.',
  options: {
    auth: serviceAccount({ fetchServiceAccountToken }),
  },
});

• When obtaining the SAT, enter the scopes that it should contain. For example, use models.read chat.completions to list models and call the inference API.
• Put the SAT returned by Token exchange in the callback result. You can also provide the SAT expiry.
• When a valid SAT cannot be obtained, return null (None in Python) or throw an exception so the current session fails explicitly.
• In Java the callback returns CompletionStage<SecretValue>. It carries only the token, with no expiry field; when no token is available, return an exceptionally completed stage. The SDK reports a fixed error message to the CLI and does not forward the callback's failure details.
• Java invokes the callback on the client's callbackExecutor. Run slow work such as HTTP requests on the application's own executor and report the result through the returned stage, as in the example above. Do not block the callback thread.
• Set connect and read timeouts on the HTTP request and release the connection when done. HttpURLConnection waits forever by default. The SDK's callback timeout (controlRequestTimeoutMs) only ends the authentication request; it does not stop an HTTP call that is still running. If the server never responds, the task keeps the executor thread busy, later authentication requests queue behind it, and the JVM cannot exit normally.

​

Reuse the local sign-in

import { qodercliAuth, query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: 'Summarize the current workspace.',
  options: {
    auth: qodercliAuth(),
  },
});

​

Authentication Failure Callback (TypeScript, Python)

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,
)

​

Authentication Errors

• Missing authentication configuration: AuthNotConfiguredError, with code == "auth_not_configured".
• Missing PAT environment variable: AuthAccessTokenEnvVarError, with code == "auth_access_token_env_var_not_configured".
• Missing Service Account Key environment variable: AuthServiceAccountEnvVarError, with code == "auth_service_account_env_var_not_configured".

• auth() was not called: QoderClient.Builder.build() throws InvalidOptionsException synchronously, and getCode() is INVALID_OPTIONS.
• The variable read by Auth.accessTokenEnv() is unset or empty: startup fails with AuthenticationException, and getCode() is AUTHENTICATION_FAILED.
• The CLI exits with an authentication failure (exit code 41): AuthenticationException with getCode() CLI_AUTH_FATAL. Java has no authentication failure callback. Catch the exception, prompt the user to sign in again or replace the credential, then create a new query or session.

​

Subprocess environment (Java)

SessionOptions.Builder options = SessionOptions.builder();
String home = System.getenv("HOME");
if (home != null) {
    options.putEnvironment("HOME", home);
}
String proxy = System.getenv("HTTPS_PROXY");
if (proxy != null) {
    options.putProxyEnvironment("HTTPS_PROXY", SecretValue.of(proxy));
}
SessionOptions sessionOptions = options.build();

• putEnvironment(String, String) adds one variable and environment(Map) adds several; neither clears variables set earlier.
• A proxy address can contain a username and password, so pass it with putProxyEnvironment(String, SecretValue). The SDK redacts its credentials in diagnostics and stderr. Proxy variables such as HTTPS_PROXY passed through putEnvironment are handled the same way.
• Credential variables managed by the SDK, such as QODER_PERSONAL_ACCESS_TOKEN, are never passed to the CLI and are stripped even when set explicitly. Authentication can only be configured through Auth.

​

Best Practices

• In production and CI, provide credentials through a secret manager; do not put credentials in source code.
• Do not write PATs, Service Account keys, or SATs to logs, error objects, or debug output.
• Configure a PAT or Service Account explicitly for automated environments instead of relying on the local qodercli sign-in.
• For user-facing applications, register the auth-expired callback to turn authentication failures into clear sign-in prompts.
• After updating or rotating credentials, create a new SDK session; do not reuse a session that has already failed authentication.