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

The Credentials inventory groups available credentials by owner. Organization rows marked proxy give the host and allowed methods/paths. Select that credential's handle (e.g. gitlab) in execute.credentials for the command making the request, with an explicit sandbox_id. Core supplies AGENT_CREDENTIAL_TOKEN only to that command; its absence before selection does not mean access is missing. Use that token, not AGENT_API_TOKEN, for broker requests.

Only listed credentials are available. A separately authorized personal login or connected app may also be available; use only its advertised capabilities and permissions. Never route around a denial or 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>" }