Connect a tool account

A tool credential connects an enrolled tool destination to an account you control. Use a human session in the selected organization and environment; an API key cannot preview or change a connection. Organization-owned connections require an owner or admin; a user-owned connection remains tied to its user.

For an enrolled OAuth provider, use Authorize a tool account instead of pasting a credential. Provider authorization and explicit account activation remain separate steps.

Review the account before connecting

List the enrolled profiles with toolCredentials.profiles in TypeScript or tool_credentials.profiles in Python. Each profile pins its version, issuer, audience, destination origin, injection header and sorted permission scopes. The profile fixes these fields; entering a credential does not select a new provider or arbitrary destination.

Call preview with the profile reference, owner_kind and secret bytes. The service performs a read-only provider check and returns the verified account subject, issuer, audience, mode, permission scopes, expiry and account digest. Show these details for review. Preview does not save a connection and does not require an idempotency key.

After the person confirms the account, call connect with that profile, owner_kind, one to 32 sorted, unique agent IDs and the reviewed expected_account_digest. Supply the secret bytes again and a new caller-chosen idempotency key. Connect independently verifies the account and refuses a mismatch. The result contains immutable version metadata and its exact reference; no response includes the secret.

A verified account preview establishes the identity and permissions reported by that provider check. It does not approve an action, authorize spending or prove that a managed tool call has executed.

Handle secret intake

The SDK takes secret bytes separately from typed metadata. A secret must contain one to 16,384 printable, non-space ASCII bytes. HTTP intake uses {request, secret_base64} for preview, connect and reconnect. Base64 is an encoding, so use the configured HTTPS API origin.

Keep secret input in memory only for the submission. Do not put it in URLs, model inputs, analytics, logs, browser storage or persisted recovery records. The SDK clears its temporary envelope after transport and does not save recovery state. Your application still controls its input field and any byte buffers it created; clear them when submission ends.

The API response contains connection metadata, never the submitted credential. The service stores the connected credential separately for authorized execution. Do not confuse that protected storage with retaining an application’s intake payload or recovery record.

Reload, reconnect or revoke

list returns up to 25 visible connection summaries per page. Pass its opaque next_cursor unchanged for the next page. A cursor expires after 15 minutes and is bound to the current session and environment authority. Discard it after an account, scope or generation change, or an invalid-cursor response. The directory contains your user-owned connections and organization-owned connections visible to current owners or admins. Listing an expired or revoked record does not make it usable for execution.

Use get with the connection ID to load its current version. getVersion in TypeScript, or get_version in Python, reads a particular immutable version. A version may be superseded; retain its exact reference when interpreting history. The required availability field distinguishes ready, refresh_required, refreshing, reconnect_required, expired, revoked and superseded. Record state active does not mean the credential is ready. Open the exact connection for current availability; the directory intentionally omits it. Always pin the selected org_id, environment_id, mode and reset_generation in SDK calls.

To reconnect, send {connection_id, expected: connection.reference}, new secret bytes and an explicit idempotency key. Reconnect requires the same verified account and creates the next immutable version. It does not switch the owner, agent allowlist or account. To revoke, send the same metadata shape and a new key, with no secret payload. Both operations check the expected current version.

No credential operation automatically retries. After an uncertain mutation, keep the same key and exact metadata. An explicit matching Connect retry returns the original immutable version even if different secret bytes are submitted; it does not rotate that version. Use reconnect for an intentional rotation. Never save the secret alongside recovery metadata. Reload the connection before starting a different change.

Revocation and credential retirement

Revocation, expiry, replacement and environment reset prevent further use of the affected credential authority. Encrypted credential data is retired asynchronously; a successful revoke or reset response does not claim that physical deletion has already completed. The cleanup process also covers abandoned credential writes whose surrounding operation did not commit.

Credential versions and operation metadata remain available where current access allows them. Charges and audit history are preserved. Cleanup does not authorize another execution or revive a retired version; reconnect requires explicit review and creates a new immutable version.

SDK calls

const scope = { org_id, environment_id, mode: 'test' as const, reset_generation };
const api = client.toolCredentials;
const profiles = await api.profiles(scope);
const review = await api.preview(scope, {
  profile: profiles.data[0].profile,
  owner_kind: 'user',
}, secretBytes);
// Show review.account and require the person's confirmation before this call.
const connection = await api.connect(scope, {
  profile: review.profile.profile,
  owner_kind: review.owner_kind,
  agents: selectedAgentIDs,
  expected_account_digest: review.account_digest,
}, secretBytes, connectKey);
const page = await api.list(scope);

Python exposes the same sequence through client.tool_credentials, accepts bytes for secret intake and uses get_version for immutable version reads. All eight SDK methods use a human session and a 40-second request timeout.

The contract fixtures use synthetic accounts and credentials. They test request boundaries and metadata validation, not a live provider account or successful external tool execution. Availability depends on the profiles and credential service enabled in the selected environment.