凭证

创建凭证

client.beta.vaults.credentials.create(vaultID, params, options?): BetaManagedAgentsCredential

POST/v1/vaults/{vault_id}/credentials

列出凭证

client.beta.vaults.credentials.list(vaultID, params?, options?): PageCursor<BetaManagedAgentsCredential>

GET/v1/vaults/{vault_id}/credentials

获取凭证

client.beta.vaults.credentials.retrieve(credentialID, params, options?): BetaManagedAgentsCredential

GET/v1/vaults/{vault_id}/credentials/{credential_id}

更新凭证

client.beta.vaults.credentials.update(credentialID, params, options?): BetaManagedAgentsCredential

POST/v1/vaults/{vault_id}/credentials/{credential_id}

删除凭证

client.beta.vaults.credentials.delete(credentialID, params, options?): BetaManagedAgentsDeletedCredential

DELETE/v1/vaults/{vault_id}/credentials/{credential_id}

归档凭证

client.beta.vaults.credentials.archive(credentialID, params, options?): BetaManagedAgentsCredential

POST/v1/vaults/{vault_id}/credentials/{credential_id}/archive

验证凭证

client.beta.vaults.credentials.mcpOAuthValidate(credentialID, params, options?): BetaManagedAgentsCredentialValidation

POST/v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate

Models

interface BetaManagedAgentsCredential { type: "vault_credential"; id; archived_at; /* 6 more */ }

A credential stored in a vault. Sensitive fields are never returned in responses.

type BetaManagedAgentsCredentialNetworkingParams = BetaManagedAgentsUnrestrictedCredentialNetworkingParams | BetaManagedAgentsLimitedCredentialNetworkingParams

One of the following:

interface BetaManagedAgentsUnrestrictedCredentialNetworkingParams { type: "unrestricted" }

Substitute the secret on any host the session's Environment network policy permits egress to. The Environment's network policy is the only boundary on where the secret can reach.

type: "unrestricted"

interface BetaManagedAgentsLimitedCredentialNetworkingParams { type: "limited"; allowed_hosts }

Substitute the secret only on requests to the listed hosts.

type: "limited"

allowed_hosts: Array<string>

Hostnames on which the secret will be substituted. Each entry is a bare hostname (api.example.com), an IPv4 address (192.0.2.1), or a *.-prefixed wildcard (*.example.com). URLs, ports, paths, and IPv6 addresses are not accepted. At most 16 entries.

interface BetaManagedAgentsCredentialValidation { type: "vault_credential_validation"; credential_id; has_refresh_token; /* 5 more */ }

Result of live-probing a credential against its configured MCP server.

type BetaManagedAgentsCredentialValidationStatus = "valid" | "invalid" | "unknown"

Overall verdict of a credential validation probe.

One of the following:

"valid"

The credential successfully authenticated against its MCP server.

"invalid"

The probe reached the MCP server and was rejected, and a refresh (if attempted) did not recover it.

"unknown"

The probe could not determine validity — for example, a transport error or a successful refresh that was not re-probed.

interface BetaManagedAgentsDeletedCredential { type: "vault_credential_deleted"; id }

Confirmation of a deleted credential.

type: "vault_credential_deleted"

id: string

Unique identifier of the deleted credential.

interface BetaManagedAgentsEnvironmentVariableAuthResponse { type: "environment_variable"; injection_location; networking; secret_name }

Environment variable credential details. The secret value is never returned.

interface BetaManagedAgentsEnvironmentVariableCreateParams { type: "environment_variable"; networking; secret_name; /* 2 more */ }

Parameters for creating an environment variable credential.

interface BetaManagedAgentsEnvironmentVariableUpdateParams { type: "environment_variable"; injection_location; networking; secret_value }

Parameters for updating an environment variable credential. secret_name is immutable.

interface BetaManagedAgentsInjectionLocationParams { body; header }

Where in the outbound request the secret value may be substituted.

body?: boolean

Substitute when the placeholder appears in the request body.

interface BetaManagedAgentsInjectionLocationResponse { body; header }

Where in the outbound request the secret value is substituted.

body: boolean

Whether the placeholder is substituted in the request body.

interface BetaManagedAgentsInjectionLocationUpdateParams { body; header }

Updated injection location.

body?: boolean

Substitute when the placeholder appears in the request body.

interface BetaManagedAgentsLimitedCredentialNetworkingParams { type: "limited"; allowed_hosts }

Substitute the secret only on requests to the listed hosts.

type: "limited"

allowed_hosts: Array<string>

interface BetaManagedAgentsLimitedCredentialNetworkingResponse { type: "limited"; allowed_hosts }

The secret is substituted only on requests to the listed hosts.

type: "limited"

allowed_hosts: Array<string>

Hostnames on which the secret will be substituted. An entry matches the request host exactly; a *.-prefixed entry matches any subdomain of the named domain but not the domain itself.

interface BetaManagedAgentsMCPOAuthAuthResponse { type: "mcp_oauth"; mcp_server_url; expires_at; refresh }

OAuth credential details for an MCP server.

type: "mcp_oauth"

mcp_server_url: string

URL of the MCP server this credential authenticates against.

expires_at?: string | null

A timestamp in RFC 3339 format

formatdate-time

refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null

Refresh token configuration, if the credential supports token refresh.

interface BetaManagedAgentsMCPOAuthCreateParams { type: "mcp_oauth"; access_token; mcp_server_url; /* 2 more */ }

Parameters for creating an MCP OAuth credential.

type: "mcp_oauth"

access_token: string

OAuth access token.

minLength1

maxLength8192

mcp_server_url: string

URL of the MCP server this credential authenticates against.

minLength1

maxLength2047

expires_at?: string | null

A timestamp in RFC 3339 format

formatdate-time

refresh?: BetaManagedAgentsMCPOAuthRefreshParams | null

Refresh token configuration, if the credential supports token refresh.

interface BetaManagedAgentsMCPOAuthRefreshParams { client_id; refresh_token; token_endpoint; /* 3 more */ }

OAuth refresh token parameters for creating a credential with refresh support.

interface BetaManagedAgentsMCPOAuthRefreshResponse { client_id; token_endpoint; token_endpoint_auth; /* 2 more */ }

OAuth refresh token configuration returned in credential responses.

interface BetaManagedAgentsMCPOAuthRefreshUpdateParams { refresh_token; scope; token_endpoint_auth }

Parameters for updating OAuth refresh token configuration.

interface BetaManagedAgentsMCPOAuthUpdateParams { type: "mcp_oauth"; access_token; expires_at; refresh }

Parameters for updating an MCP OAuth credential. The mcp_server_url is immutable.

type: "mcp_oauth"

access_token?: string | null

Updated OAuth access token.

minLength1

maxLength8192

expires_at?: string | null

A timestamp in RFC 3339 format

formatdate-time

refresh?: BetaManagedAgentsMCPOAuthRefreshUpdateParams | null

Updated refresh token configuration.

interface BetaManagedAgentsMCPProbe { http_response; method }

The failing step of an MCP validation probe.

http_response: BetaManagedAgentsRefreshHTTPResponse | null

The captured HTTP error response. Null when no HTTP response was received (timeout, DNS, TLS).

body: string

Response body. May be truncated and has sensitive values scrubbed.

body_truncated: boolean

Whether body was truncated.

content_type: string

Value of the Content-Type response header.

status_code: number

HTTP status code.

formatint32

method: string

The MCP method that failed (for example initialize or tools/list).

interface BetaManagedAgentsRefreshHTTPResponse { body; body_truncated; content_type; status_code }

An HTTP response captured during a credential validation probe.

body: string

Response body. May be truncated and has sensitive values scrubbed.

body_truncated: boolean

Whether body was truncated.

content_type: string

Value of the Content-Type response header.

status_code: number

HTTP status code.

formatint32

interface BetaManagedAgentsRefreshObject { http_response; status }

Outcome of a refresh-token exchange attempted during credential validation.

http_response: BetaManagedAgentsRefreshHTTPResponse | null

The captured HTTP error response from the token endpoint. Populated only when status is failed.

body: string

Response body. May be truncated and has sensitive values scrubbed.

body_truncated: boolean

Whether body was truncated.

content_type: string

Value of the Content-Type response header.

status_code: number

HTTP status code.

formatint32

status: "succeeded" | "failed" | "connect_error" | "no_refresh_token"

Outcome of the refresh attempt.

One of the following:

"succeeded"

The token endpoint returned a new access token.

"failed"

The token endpoint returned an error response. See http_response for detail.

"connect_error"

The token endpoint could not be reached (DNS, TLS, or connection error).

"no_refresh_token"

No refresh token is stored for the credential, so no exchange was attempted.

interface BetaManagedAgentsStaticBearerAuthResponse { type: "static_bearer"; mcp_server_url }

Static bearer token credential details for an MCP server.

type: "static_bearer"

mcp_server_url: string

URL of the MCP server this credential authenticates against.

interface BetaManagedAgentsStaticBearerCreateParams { type: "static_bearer"; token; mcp_server_url }

Parameters for creating a static bearer token credential.

type: "static_bearer"

token: string

Static bearer token value.

minLength1

maxLength8192

mcp_server_url: string

URL of the MCP server this credential authenticates against.

minLength1

maxLength2047

interface BetaManagedAgentsStaticBearerUpdateParams { type: "static_bearer"; token }

Parameters for updating a static bearer token credential. The mcp_server_url is immutable.

type: "static_bearer"

token?: string | null

Updated static bearer token value.

minLength1

maxLength8192

interface BetaManagedAgentsTokenEndpointAuthBasicParam { type: "client_secret_basic"; client_secret }

Token endpoint uses HTTP Basic authentication with client credentials.

type: "client_secret_basic"

client_secret: string

OAuth client secret.

minLength1

maxLength512

interface BetaManagedAgentsTokenEndpointAuthBasicResponse { type: "client_secret_basic" }

Token endpoint uses HTTP Basic authentication with client credentials.

type: "client_secret_basic"

interface BetaManagedAgentsTokenEndpointAuthBasicUpdateParam { type: "client_secret_basic"; client_secret }

Updated HTTP Basic authentication parameters for the token endpoint.

type: "client_secret_basic"

client_secret?: string | null

Updated OAuth client secret.

minLength1

maxLength512

interface BetaManagedAgentsTokenEndpointAuthNoneParam { type: "none" }

Token endpoint requires no client authentication.

type: "none"

interface BetaManagedAgentsTokenEndpointAuthNoneResponse { type: "none" }

Token endpoint requires no client authentication.

type: "none"

interface BetaManagedAgentsTokenEndpointAuthPostParam { type: "client_secret_post"; client_secret }

Token endpoint uses POST body authentication with client credentials.

type: "client_secret_post"

client_secret: string

OAuth client secret.

minLength1

maxLength512

interface BetaManagedAgentsTokenEndpointAuthPostResponse { type: "client_secret_post" }

Token endpoint uses POST body authentication with client credentials.

type: "client_secret_post"

interface BetaManagedAgentsTokenEndpointAuthPostUpdateParam { type: "client_secret_post"; client_secret }

Updated POST body authentication parameters for the token endpoint.

type: "client_secret_post"

client_secret?: string | null

Updated OAuth client secret.

minLength1

maxLength512

interface BetaManagedAgentsUnrestrictedCredentialNetworkingParams { type: "unrestricted" }

Substitute the secret on any host the session's Environment network policy permits egress to. The Environment's network policy is the only boundary on where the secret can reach.

type: "unrestricted"

interface BetaManagedAgentsUnrestrictedCredentialNetworkingResponse { type: "unrestricted" }

The secret is substituted on any host the session's Environment network policy permits egress to.

type: "unrestricted"