Handling API 401 & Token Expiration
Relevant source files
The following files were used as context for generating this wiki page:
Handling authentication failures and token expiration is a core function of the ollacc launcher. Since the application acts as a bridge between the Anthropic SDK (Claude Code) and the Ollama Cloud API, it must ensure that a valid ANTHROPIC_AUTH_TOKEN is present and functional before executing the primary payload.
The system implements a proactive check and a reactive recovery strategy. Proactively, it validates the presence of a token and attempts to fetch an authorized catalog. Reactively, it provides administrative flags to clear stale credentials, allowing the user to re-authenticate when the API returns a 401 Unauthorized error. Sources: README.md:143-145, lib/auth.sh:22-24
Authentication Architecture
The authentication flow relies on environment variables and a local configuration file stored at ~/.ollacc/config. This file is protected with chmod 600 to ensure that only the owner can read the sensitive API key. Sources: install.sh:45-56, lib/auth.sh:43
Token Storage and Environment
The system manages three specific environment variables required by the Anthropic SDK to redirect traffic to https://ollama.com.
| Environment Variable | Purpose | Value/Source |
|---|---|---|
ANTHROPIC_BASE_URL | The API endpoint host | https://ollama.com |
ANTHROPIC_AUTH_TOKEN | The Bearer token for auth | Loaded from ~/.ollacc/config |
ANTHROPIC_API_KEY | Overriding SDK key | Must be empty "" |
Sources: lib/auth.sh:53-58, README.md:162-171
The following diagram illustrates the token initialization and validation flow:
The flow ensures that the launcher does not proceed without a token and defines the path for recovery if the token is invalid. Sources: lib/auth.sh:10-50, lib/catalog.sh:28-35
Handling API 401 Unauthorized
When the Ollama Cloud API returns a 401 error, it typically indicates that the ANTHROPIC_AUTH_TOKEN has expired or is invalid. The ollacc system handles this primarily through its catalog resolution logic.
Catalog Resolution and Fail-on-Error
The function catalog_resolve uses curl with the -sf flags. The -f (fail) flag ensures that if the server returns an HTTP 401 (or any 4xx/5xx), curl returns a non-zero exit code and produces an empty body rather than error text. Sources: lib/catalog.sh:28-35
if ! authd_json=$(curl -sf --max-time 10 --connect-timeout 5 \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
"https://ollama.com/api/tags"); then
authd_json=""
fi
Sources: lib/catalog.sh:33-37
If the token is invalid (401), authd_json becomes empty. This triggers a fallback mechanism where the launcher attempts to use a hardcoded list of models or warns the user that the catalog could not be reached. Sources: lib/catalog.sh:58-75
Token Expiration Recovery
The system provides a manual reset mechanism for users to recover from expired tokens. If a user encounters persistent 401 errors, they are instructed to clear the saved key. Sources: README.md:110-112
The --key-clear Mechanism
The flags_handle function in lib/flags.sh identifies the --key-clear argument. It utilizes config_unset to remove the token from the configuration file without deleting other settings like the base URL. Sources: lib/flags.sh:18-26
- Detection: The launcher checks for
--key-clearbefore sourcing the full configuration. - Unset: It calls
config_unset ANTHROPIC_AUTH_TOKEN. - Execution: On the next run,
auth_prompt_if_missingdetects the empty variable and re-prompts the user for a new key.
Configuration Management Functions
The following functions in lib/config.sh are critical for maintaining the integrity of the authentication data during updates or deletions.
| Function | Description | Implementation Detail |
|---|---|---|
config_set | Updates or creates a key-value pair. | Uses bash_escape and awk to preserve comments. |
config_unset | Removes a key-value pair. | Uses mktemp and awk for atomic updates. |
bash_escape | Sanitizes input strings. | Escapes \, $, `, and ". |
Sources: lib/config.sh:31-69
Summary
ollacc manages API 401 errors and token expiration through a combination of silent failover in catalog resolution and explicit state management flags. By storing credentials in a chmod 600 config file and providing a dedicated --key-clear path, the system allows users to rotate expired tokens easily while maintaining secure local storage. Sources: README.md:110-112, lib/auth.sh:43