Salesforce Models API setup for an AI coding agent
The Salesforce Models API (https://api.salesforce.com/ai/gpt/v1) is
authenticated with a signed OrgJWT (obtained via client_credentials with
the sfap_api scope — see scripts/get-orgjwt.sh; no proxy). That auth and the
base URL are the same for any agent. How each agent then talks to the
endpoint is agent-specific: Anthropic clients (Claude Code and the Claude
Agent SDK) route through Bedrock mode (the env vars in Step 3), whereas
other agents (e.g. Codex) use their own client config against the same endpoint
and token — Bedrock mode does not apply to them.
The steps below are the Claude Code / Claude Agent SDK reference
implementation (Bedrock mode + a JSON settings file + an API-key helper). For
a non-Bedrock agent, reuse the OrgJWT auth (Step 1) and the base URL, and apply
the equivalent client settings in that agent's own config location instead of
the Bedrock env vars.
Bundled scripts are in scripts/. Path placeholders below: <SKILL> = the
absolute path to this skill's own directory (the folder containing this
SKILL.md; resolve it from the skill path in context). <ABS> = the absolute
path to the user's project root. Always emit fully resolved absolute paths —
the API-key helper runs from an undefined working directory, so relative paths
break it.
Prerequisite
A connected app in the org with the sfap_api OAuth scope and the
client_credentials flow enabled (consumer key/secret + a run-as user).
Setup steps: https://developer.salesforce.com/docs/ai/agentforce/guide/access-models-api-with-rest.html
curl + jq installed.
Inputs to collect
SF_INSTANCE_URL — org My Domain, e.g. https://acme.my.salesforce.com
SF_CLIENT_ID, SF_CLIENT_SECRET — connected-app consumer key/secret
- Models API base URL:
https://api.salesforce.com/ai/gpt/v1
- Model: a fully qualified
sfdc_ai__… name, e.g.
sfdc_ai__DefaultBedrockAnthropicClaude46Sonnet
(full list: https://developer.salesforce.com/docs/ai/agentforce/guide/supported-models.html)
- Scope: project (
<cwd>/.claude/settings.json, default) or user (~/.claude/settings.json) — reference-agent settings paths
- Headers —
<FEAT> = x-client-feature-id (default ai-platform-models-connected-app),
<APP> = x-sfdc-app-context (default EinsteinGPT). Used in the Step 2 verify curl
and in ANTHROPIC_CUSTOM_HEADERS.
Steps (reference implementation)
Concrete values for a JSON-settings + API-key-helper agent. Reuse the OrgJWT
auth, verify curl, and base URL verbatim for any agent; adapt the settings-file
location and env-var wiring to the target agent.
- Write
<project>/.claude/.orgjwt.env (chmod 600), gitignore it:SF_INSTANCE_URL="..."
SF_CLIENT_ID="..."
SF_CLIENT_SECRET="..."
- Verify — must return
200 before writing settings:TOKEN=$(bash <SKILL>/scripts/get-orgjwt.sh <ABS>/.claude/.orgjwt.env)
curl -s -o /dev/null -w '%{http_code}\n' \
<MODELS_API_URL>/model/<MODEL>/invoke-with-response-stream \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-H 'x-client-feature-id: <FEAT>' -H 'x-sfdc-app-context: <APP>' \
--data '{"anthropic_version":"bedrock-2023-05-31","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'
- Write
.claude/settings.json (merge into existing; keep other keys):{
"apiKeyHelper": "bash <SKILL>/scripts/get-orgjwt.sh <ABS>/.claude/.orgjwt.env",
"model": "<MODEL>",
"env": {
"ANTHROPIC_AUTH_TOKEN": "",
"CLAUDE_CODE_USE_BEDROCK": "1",
"CLAUDE_CODE_SKIP_BEDROCK_AUTH": "1",
"ANTHROPIC_BEDROCK_BASE_URL": "<MODELS_API_URL>",
"ANTHROPIC_SMALL_FAST_MODEL": "<MODEL>",
"ANTHROPIC_DEFAULT_MODEL": "<MODEL>",
"ANTHROPIC_CUSTOM_HEADERS": "x-client-feature-id: <FEAT>\nx-sfdc-app-context: <APP>"
}
}
Use absolute paths in apiKeyHelper. (<FEAT> / <APP> defaults are in
"Inputs to collect" above.)
- Tell the admin to fully restart the agent (
claude for the reference agent) —
settings and the API-key helper load at startup only.
Capturing as a runbook (when asked to document, not apply)
If the user wants the setup written up for review instead of applied to their
machine (e.g. "save it as a Markdown runbook"), write all of the above into
the requested file (e.g. models-api-setup-runbook.md), in order and self-contained:
the exact .orgjwt.env contents, the chmod 600 + gitignore note, the
verification curl (with the "must be 200 before writing settings" note), the
full settings.json block with every key from Step 3, and the final
"fully restart claude" step. Don't omit any of the nine settings.json keys.
Verify before finishing
Must be exact (each prevents a specific failure)
"ANTHROPIC_AUTH_TOKEN": "" — clears any global token that would otherwise
outrank apiKeyHelper (precedence: ANTHROPIC_AUTH_TOKEN > ANTHROPIC_API_KEY
apiKeyHelper). Without it → wrong/old bearer → 401/404.
CLAUDE_CODE_USE_BEDROCK=1 — activates the Bedrock API client; without it
Claude Code uses the standard Anthropic API protocol and ignores
ANTHROPIC_BEDROCK_BASE_URL entirely, so every call bypasses the Models API.
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1 — else Claude Code overwrites Authorization
with AWS SigV4 and the OrgJWT never lands.
apiKeyHelper must be invoked as bash <path> <credsfile> (avoids exit-126).
- Model must be a fully qualified
sfdc_ai__… name (see supported models).
- Auth is the OrgJWT from
client_credentials (a signed JWT, 2 dots, scope
sfap_api) — NOT sf org display (unsigned session token → 404). sf CLI
has no client_credentials command; the helper calls /services/oauth2/token.
- Only
ANTHROPIC_BEDROCK_BASE_URL routes; no tenant-id header needed.
Diagnose
| Error |
Meaning |
Check first |
401 |
Token is not a valid OrgJWT |
Connected App sfap_api scope, client_credentials flow enabled, consumer key/secret in .orgjwt.env; ANTHROPIC_AUTH_TOKEN not cleared to "" |
404 |
Token valid but model/env/org not routable |
Fully qualified sfdc_ai__… model alias, ANTHROPIC_BEDROCK_BASE_URL exactly https://api.salesforce.com/ai/gpt/v1, org entitled for the Models API, ANTHROPIC_AUTH_TOKEN cleared |
model not available |
Non-alias model id |
Replace with a fully qualified sfdc_ai__… alias (see supported models) |
1---2name: platform-models-api-configure3description: "Configure (or troubleshoot) an AI coding agent or CLI to route through the Salesforce Models API using a signed OrgJWT. Use this skill when pointing an agent at the Salesforce model endpoint (api.salesforce.com/ai/gpt/v1), setting up OrgJWT / Bedrock-mode auth, wiring the agent's settings, API-key helper, and credentials file for the Salesforce endpoint, or fixing Models API 401 / 404 / \"model not available\" errors. DO NOT TRIGGER when the user needs to create or configure the Salesforce Connected App itself (use integration-connectivity-connected-app-configure) or set up Named Credentials / callout auth (use integration-connectivity-generate)."4metadata:5 source: https://skillmd.com/skills/agentcorp-inc/platform-models-api-configure6 version: "1.0"7---89# Salesforce Models API setup for an AI coding agent1011The Salesforce Models API (`https://api.salesforce.com/ai/gpt/v1`) is12authenticated with a signed **OrgJWT** (obtained via `client_credentials` with13the `sfap_api` scope — see `scripts/get-orgjwt.sh`; no proxy). That auth and the14base URL are the same for **any** agent. How each agent then talks to the15endpoint is agent-specific: Anthropic clients (**Claude Code** and the **Claude16Agent SDK**) route through **Bedrock mode** (the env vars in Step 3), whereas17other agents (e.g. Codex) use their own client config against the same endpoint18and token — Bedrock mode does **not** apply to them.1920The steps below are the **Claude Code / Claude Agent SDK reference21implementation** (Bedrock mode + a JSON settings file + an API-key helper). For22a non-Bedrock agent, reuse the OrgJWT auth (Step 1) and the base URL, and apply23the equivalent client settings in that agent's own config location instead of24the Bedrock env vars.2526Bundled scripts are in `scripts/`. Path placeholders below: `<SKILL>` = the27absolute path to **this skill's own directory** (the folder containing this28`SKILL.md`; resolve it from the skill path in context). `<ABS>` = the absolute29path to the user's project root. Always emit fully resolved absolute paths —30the API-key helper runs from an undefined working directory, so relative paths31break it.3233## Prerequisite3435A connected app in the org with the **`sfap_api`** OAuth scope and the36**client_credentials** flow enabled (consumer key/secret + a run-as user).37Setup steps: https://developer.salesforce.com/docs/ai/agentforce/guide/access-models-api-with-rest.html38`curl` + `jq` installed.3940## Inputs to collect4142- `SF_INSTANCE_URL` — org My Domain, e.g. `https://acme.my.salesforce.com`43- `SF_CLIENT_ID`, `SF_CLIENT_SECRET` — connected-app consumer key/secret44- Models API base URL: `https://api.salesforce.com/ai/gpt/v1`45- Model: a fully qualified `sfdc_ai__…` name, e.g.46 `sfdc_ai__DefaultBedrockAnthropicClaude46Sonnet`47 (full list: https://developer.salesforce.com/docs/ai/agentforce/guide/supported-models.html)48- Scope: project (`<cwd>/.claude/settings.json`, default) or user (`~/.claude/settings.json`) — reference-agent settings paths49- Headers — `<FEAT>` = `x-client-feature-id` (default `ai-platform-models-connected-app`),50 `<APP>` = `x-sfdc-app-context` (default `EinsteinGPT`). Used in the Step 2 verify curl51 and in `ANTHROPIC_CUSTOM_HEADERS`.5253## Steps (reference implementation)5455Concrete values for a JSON-settings + API-key-helper agent. Reuse the OrgJWT56auth, verify curl, and base URL verbatim for any agent; adapt the settings-file57location and env-var wiring to the target agent.58591. Write `<project>/.claude/.orgjwt.env` (chmod 600), gitignore it:60 ```ini61 SF_INSTANCE_URL="..."62 SF_CLIENT_ID="..."63 SF_CLIENT_SECRET="..."64 ```652. Verify — must return `200` before writing settings:66 ```bash67 TOKEN=$(bash <SKILL>/scripts/get-orgjwt.sh <ABS>/.claude/.orgjwt.env)68 curl -s -o /dev/null -w '%{http_code}\n' \69 <MODELS_API_URL>/model/<MODEL>/invoke-with-response-stream \70 -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \71 -H 'x-client-feature-id: <FEAT>' -H 'x-sfdc-app-context: <APP>' \72 --data '{"anthropic_version":"bedrock-2023-05-31","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'73 ```743. Write `.claude/settings.json` (merge into existing; keep other keys):75 ```json76 {77 "apiKeyHelper": "bash <SKILL>/scripts/get-orgjwt.sh <ABS>/.claude/.orgjwt.env",78 "model": "<MODEL>",79 "env": {80 "ANTHROPIC_AUTH_TOKEN": "",81 "CLAUDE_CODE_USE_BEDROCK": "1",82 "CLAUDE_CODE_SKIP_BEDROCK_AUTH": "1",83 "ANTHROPIC_BEDROCK_BASE_URL": "<MODELS_API_URL>",84 "ANTHROPIC_SMALL_FAST_MODEL": "<MODEL>",85 "ANTHROPIC_DEFAULT_MODEL": "<MODEL>",86 "ANTHROPIC_CUSTOM_HEADERS": "x-client-feature-id: <FEAT>\nx-sfdc-app-context: <APP>"87 }88 }89 ```90 Use absolute paths in `apiKeyHelper`. (`<FEAT>` / `<APP>` defaults are in91 "Inputs to collect" above.)924. Tell the admin to fully restart the agent (`claude` for the reference agent) —93 settings and the API-key helper load at startup only.9495### Capturing as a runbook (when asked to document, not apply)9697If the user wants the setup written up for review instead of applied to their98machine (e.g. "save it as a Markdown runbook"), write **all** of the above into99the requested file (e.g. `models-api-setup-runbook.md`), in order and self-contained:100the exact `.orgjwt.env` contents, the `chmod 600` + gitignore note, the101verification curl (with the "must be `200` before writing settings" note), the102full `settings.json` block with every key from Step 3, and the final103"fully restart `claude`" step. Don't omit any of the nine `settings.json` keys.104105## Verify before finishing106107- [ ] `.claude/.orgjwt.env` created, `chmod 600`, and gitignored108- [ ] Verification curl returned HTTP `200` before `settings.json` was written109- [ ] `ANTHROPIC_AUTH_TOKEN` set to `""` in `settings.json`110- [ ] `CLAUDE_CODE_USE_BEDROCK` set to `"1"`111- [ ] `CLAUDE_CODE_SKIP_BEDROCK_AUTH` set to `"1"`112- [ ] `ANTHROPIC_BEDROCK_BASE_URL` is exactly `https://api.salesforce.com/ai/gpt/v1` (no trailing slash/path)113- [ ] `model`, `ANTHROPIC_DEFAULT_MODEL`, and `ANTHROPIC_SMALL_FAST_MODEL` all use the fully qualified `sfdc_ai__…` alias114- [ ] `ANTHROPIC_CUSTOM_HEADERS` contains `x-client-feature-id` and `x-sfdc-app-context`115- [ ] `apiKeyHelper` uses absolute paths (`bash <SKILL>/scripts/get-orgjwt.sh <ABS>/.claude/.orgjwt.env`)116- [ ] User told to fully restart `claude`117118## Must be exact (each prevents a specific failure)119120- `"ANTHROPIC_AUTH_TOKEN": ""` — clears any global token that would otherwise121 outrank `apiKeyHelper` (precedence: `ANTHROPIC_AUTH_TOKEN` > `ANTHROPIC_API_KEY`122 > `apiKeyHelper`). Without it → wrong/old bearer → 401/404.123- `CLAUDE_CODE_USE_BEDROCK=1` — activates the Bedrock API client; without it124 Claude Code uses the standard Anthropic API protocol and ignores125 `ANTHROPIC_BEDROCK_BASE_URL` entirely, so every call bypasses the Models API.126- `CLAUDE_CODE_SKIP_BEDROCK_AUTH=1` — else Claude Code overwrites `Authorization`127 with AWS SigV4 and the OrgJWT never lands.128- `apiKeyHelper` must be invoked as `bash <path> <credsfile>` (avoids exit-126).129- Model must be a fully qualified `sfdc_ai__…` name (see supported models).130- Auth is the OrgJWT from `client_credentials` (a signed JWT, 2 dots, scope131 `sfap_api`) — NOT `sf org display` (unsigned session token → 404). `sf` CLI132 has no client_credentials command; the helper calls `/services/oauth2/token`.133- Only `ANTHROPIC_BEDROCK_BASE_URL` routes; no tenant-id header needed.134135## Diagnose136137| Error | Meaning | Check first |138|-------|---------|-------------|139| `401` | Token is not a valid OrgJWT | Connected App `sfap_api` scope, `client_credentials` flow enabled, consumer key/secret in `.orgjwt.env`; `ANTHROPIC_AUTH_TOKEN` not cleared to `""` |140| `404` | Token valid but model/env/org not routable | Fully qualified `sfdc_ai__…` model alias, `ANTHROPIC_BEDROCK_BASE_URL` exactly `https://api.salesforce.com/ai/gpt/v1`, org entitled for the Models API, `ANTHROPIC_AUTH_TOKEN` cleared |141| `model not available` | Non-alias model id | Replace with a fully qualified `sfdc_ai__…` alias (see supported models) |