Authentication
Interactive Redgold clients use an account session. API clients use an sk-rg- key. Both credentials are sent as bearer tokens, but their lifecycle differs.
API keys
Create a key from the API-key page in the signed-in web application. The complete value is shown once. Store it in a secret manager or environment variable and revoke it when it is no longer needed.
export REDGOLD_API_KEY=sk-rg-...
curl https://api.redgold.ai/v1/models \
-H "Authorization: Bearer $REDGOLD_API_KEY"
Send the key in the Authorization: Bearer header. The model API reads the credential only from that header (and, for the signed-in web application, the session cookie); it does not read an X-Api-Key header, so a request that supplies the key only as X-Api-Key is rejected with 401.
CLI credential file
rac, rci, and rdg can read a key from ~/.redgold/credentials.toml:
api_key = "sk-rg-..."
A nonempty REDGOLD_API_KEY environment variable takes precedence. When it is
unset or blank, the CLI loads the file key into its process environment so
delegated commands use it too. Missing files and missing or blank api_key
values leave the existing authentication fallbacks available. An unreadable or
invalid file produces an error without printing its contents.
Keep this file private (chmod 600 ~/.redgold/credentials.toml on Unix).
Install scripts and other API clients still require their documented credentials.
XMPP with the same API key
rac xmpp install installs the private Slixmpp environment. Bind the key to
your workspace with rac xmpp connect --workspace <workspace>, then run
rac xmpp check to verify the connection. The returned JID identifies this
key and workspace. Use --server <https-api-origin> for a different API realm.
Cloud runtimes that require an HTTP proxy can use XMPP over HTTPS BOSH:
rac xmpp connect --workspace <workspace> --transport bosh
rac xmpp check
The transport choice is saved with the connection. The default auto selects
BOSH when an HTTPS proxy or BOSH-only proxy applies; NO_PROXY is respected.
Otherwise it uses direct TLS. An explicit --transport direct or --transport bosh overrides
the saved choice for an operation. Supply your runtime's approved HTTPS proxy
configuration and trusted CA configuration through its normal environment.
TLS verification is required, and credential-bearing redirects are refused.
When the identity API and BOSH endpoint need different approved proxies, keep
the normal proxy environment for the API and set RAC_XMPP_BOSH_PROXY to the
BOSH endpoint's HTTP CONNECT proxy. The equivalent per-command option is
--bosh-proxy <http-proxy-url>. This override affects only BOSH; NO_PROXY
and trusted CA configuration still apply. Proxy settings remain runtime
configuration and are not saved by connect. Use --server for the HTTPS API
origin reachable through the API proxy, and verify the returned JID/workspace.
rac xmpp send returns a stable stanza ID and reports submitted until a peer
receipt confirms delivered. rac xmpp receive reads durable archive history;
retain its cursor after handling a page. Both transports use the same identity
and archive. rac xmpp disconnect disables only the XMPP grant; the account
API key continues to work for other commands.
Account sessions
The web application establishes an account session during sign-in and uses it for interactive requests. Treat the session as a user credential. Do not copy it into source code or use it as a long-lived CI secret.
Some account-management operations, including minting a new API key, require an account session and do not accept an existing API key as authority to create another key.
Credential handling
- Keep keys out of repositories, prompts, logs, and screenshots.
- Give each automation context its own key so it can be revoked independently.
- Use the lowest practical request limit for unattended clients.
- Replace a key if its value may have been exposed.
Authentication failures
A missing, malformed, revoked, or unknown key returns 401. An account out of model-API credits returns 402. On the data API a valid identity without permission for an operation returns 403; the model endpoints do not emit 403. Model endpoints return the error envelope matching their OpenAI or Anthropic request shape.