credential-proxy

name	credential-proxy
description	How to make authenticated API calls to external services. Covers api.sh, cred-exec, auth patterns, available credentials, cloning repos, SSH forwarding, and troubleshooting 401s. Read this before calling any external API or using a CLI tool that needs auth.

Credential Proxy — Authenticated API Access

All external API calls go through the credential proxy via /workspace/scripts/api.sh. The proxy injects real credentials at request time — your environment variables contain placeholders, not real secrets.

The One Rule

ALWAYS use /workspace/scripts/api.sh for authenticated HTTP requests. Never use raw curl, gh, git clone with SSH, or any other tool that bypasses the proxy — unless you wrap it with cred-exec.sh (see below).

/workspace/scripts/api.sh <service_label> <METHOD> <URL> [CURL_ARGS...]

The first argument is a service label (for logging). The rest is passed to curl.

CLI tools — cred-exec

For CLI tools that need credentials (gh, glab, aws, etc.), use cred-exec.sh to inject a real credential for the duration of a single command:

/workspace/scripts/cred-exec.sh <service> <env_var> -- <command...>

It fetches the real credential from the proxy and sets it as <env_var> only for the child process. The credential never touches disk or the container's global environment.

# GitHub CLI
/workspace/scripts/cred-exec.sh github GITHUB_TOKEN -- gh pr list

# Any CLI tool that reads auth from an env var
/workspace/scripts/cred-exec.sh myservice MY_API_KEY -- some-cli --flag

Which tool when

Scenario	Tool
HTTP API calls (REST, GraphQL)	api.sh
CLI tools (gh, glab, aws, jira, etc.)	cred-exec.sh
git clone / git push over HTTPS	cred-exec.sh

Per-service auth patterns

For concrete invocations against GitHub, GitLab, Atlassian, Harness, LaunchDarkly, BlackDuck, and custom services: Read references/auth-patterns.md.

Quickly check what's wired in this container:

env | grep -E '_(TOKEN|KEY|SECRET|URL|EMAIL)=' | sed 's/=.*//' | sort

Cloning repositories

For HTTPS clone (preferred), API-based file fetches, SSH-agent forwarding, and the "ask for a local mount" fallback: Read references/cloning.md.

Quick form:

/workspace/scripts/cred-exec.sh github GITHUB_TOKEN -- \
  git clone https://x-access-token:${GITHUB_TOKEN}@github.com/OWNER/REPO.git /workspace/group/repo-name

Registering new credentials

If a service returns 401 and you've confirmed you're using api.sh with the right auth header:

Use mcp__nanoclaw__request_credential with:
- service: "service-name"
- description: "Why this credential is needed"

This opens a popup in the user's browser. The credential is available immediately — no restart needed. A [credential_registered] message appears in chat when complete.

Troubleshooting

Symptom	Cause	Fix
401 Unauthorized	Not using api.sh or cred-exec	Switch from raw curl/gh to api.sh or cred-exec.sh
401 Unauthorized	Missing auth header	Add -H "Authorization: token $TOKEN" or equivalent
401 Unauthorized	Credential expired/missing	Use request_credential to re-register
410 Gone	Deprecated Jira endpoint	Use /rest/api/3/search/jql POST instead of /rest/api/3/search GET
Connection refused	Wrong base URL	Check env | grep _URL for the correct service URL
Empty response	Placeholder not substituted	Verify the env var name matches exactly (case-sensitive)
cred-exec fails	CRED_PROXY_URL not set	You're likely not in a container — use api.sh on the host

Key rules

1. Always api.sh — never raw curl for authenticated HTTP calls.
2. Always cred-exec.sh — for CLI tools that need credentials (gh, glab, etc.).
3. Always pass auth headers — the proxy substitutes placeholders, it doesn't add headers.
4. Never echo credentials — env vars contain placeholders, but don't log them anyway.
5. Never ask users to paste tokens — use request_credential instead.
6. Try first, ask second — attempt the API call before requesting new credentials.