use-shared-credential

Use a shared org credential (by proxy, never the raw secret)

Some credentials aren't yours and aren't on your computer — they're one org credential the admin vends to people, like a shared doc: an org web-search key, a paid-API key, a data-vendor feed. You are NOT given the secret (a shared bearer sitting in your shell could leak). Instead you make the call by proxy: you name the credential + the request, and the core stamps the secret onto the outbound call at the wire and returns the response.

When this applies

Your system prompt lists, under "Shared org credentials available to you", any credentials vended to this conversation — each with its slug, host, and the methods/paths you may use. If that section is absent (or your environment has no AGENT_CREDENTIAL_TOKEN), you have none — do not try to reach those services another way, and don't ask the user to paste a token.

How to call it

curl -fsS -X POST "$AGENT_API_URL/v1/credentials/broker" \
  -H "x-agent-capability: $AGENT_CREDENTIAL_TOKEN" \
  -H "content-type: application/json" \
  -d '{
        "credential": "<slug from your system prompt>",
        "method": "GET",
        "url": "https://<the credential's host>/<allowed path>?<query>",
        "headers": { "accept": "application/json" }
      }'

The reply is an envelope — the upstream status + body, never the secret:

{ "status": 200, "contentType": "application/json", "body": "<the upstream response text>" }

Parse body as the upstream returned it (e.g. JSON). For a write (when the credential allows a non-GET method), put the request payload in the body field of your POST.

Git smart HTTP remotes

Some shared credentials are for Git remotes, where git clone, git fetch, and git push speak Git's smart HTTP protocol instead of JSON REST. Do not put the upstream token in a clone URL. Use the core-hosted remote path instead:

git remote add broker "$AGENT_API_URL/v1/credentials/git/<slug>/<repo-path>.git"
git -c http.extraHeader="x-agent-capability: $AGENT_CREDENTIAL_TOKEN" \
  push broker HEAD:refs/heads/codex/small-change