Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested
Overview Models Agents Tools Audio & voice Production API reference

Vaults

Create a vault
POST/vaults
Delete a vault
DELETE/vaults/{vault_id}
List vaults
GET/vaults
Retrieve a vault
GET/vaults/{vault_id}
Update a vault
POST/vaults/{vault_id}
ModelsExpand Collapse
Vault object { id, created_at, metadata, 2 more }

A collection of credentials for MCP servers and OpenAI-hosted environments.

id: string

The ID of the vault.

minLength0
created_at: number

The Unix timestamp, in seconds, when the vault was created.

formatint64
metadata: map[string]

Key-value pairs associated with the vault, such as an application or team identifier.

name: string or null

The human-readable name of the vault, if set.

minLength0
object: "vault"

The object type. Always vault.

VaultDeleted object { id, deleted, object }

Confirmation that a vault was deleted.

id: string

The ID of the deleted vault.

minLength0
deleted: boolean

Whether the resource was deleted. Always true.

object: "vault.deleted"

The object type. Always vault.deleted.

VaultStatus = "active" or "archived"

Whether a vault or credential is active or archived.

One of the following:
"active"
"archived"
VaultStatusFilter = VaultStatus or array of VaultStatus

One or more lifecycle statuses to include when listing vaults or credentials.

One of the following:
VaultStatus = "active" or "archived"

Whether a vault or credential is active or archived.

One of the following:
"active"
"archived"
array of VaultStatus
One of the following:
"active"
"archived"

VaultsCredentials

Create a vault credential
POST/vaults/{vault_id}/credentials
Delete a vault credential
DELETE/vaults/{vault_id}/credentials/{credential_id}
List vault credentials
GET/vaults/{vault_id}/credentials
Retrieve a vault credential
GET/vaults/{vault_id}/credentials/{credential_id}
Update a vault credential
POST/vaults/{vault_id}/credentials/{credential_id}
ModelsExpand Collapse
Credential object { id, auth, created_at, 5 more }

Metadata for a stored credential. Secret values are never returned.

id: string

The ID of the credential.

minLength0
auth: CredentialAuth

The authentication method and non-secret configuration of the credential.

created_at: number

The Unix timestamp, in seconds, when the credential was created.

formatint64
metadata: map[string]

Application-defined key-value pairs associated with this credential.

name: string

The human-readable name of the credential.

minLength0
object: "vault.credential"

The object type. Always vault.credential.

updated_at: number

The Unix timestamp, in seconds, when the credential was last updated.

formatint64
vault_id: string

The ID of the vault containing this credential.

minLength0
CredentialAuth = McpOauth { expires_at, mcp_server_url, refresh, type } or StaticBearer { mcp_server_url, type } or EnvironmentVariable { networking, secret_name, type }

The authentication configuration of a vault credential, excluding secrets.

One of the following:
McpOauth object { expires_at, mcp_server_url, refresh, type }

Public metadata for an OAuth credential; tokens and client secrets are never returned.

expires_at: string or null

When the OAuth access token expires, as an RFC 3339 timestamp, if known.

minLength0
mcp_server_url: string

The HTTPS MCP server URL authorized by this credential.

minLength0
refresh: object { client_id, resource, scope, 2 more } or null

Public refresh metadata without refresh tokens or OAuth client secrets.

client_id: string

The OAuth client ID used when requesting a new access token.

minLength0
resource: string or null

The resource URI sent to the OAuth token endpoint during refresh, if configured.

minLength0
scope: string or null

Space-separated OAuth scopes requested during refresh, if configured.

minLength0
token_endpoint: string

The HTTPS OAuth token endpoint used for refresh.

minLength0
token_endpoint_auth: McpOauthTokenEndpointAuth

How the OAuth client authenticates to the token endpoint, excluding its client secret.

type: "mcp_oauth"

The type of the object. Always mcp_oauth.

StaticBearer object { mcp_server_url, type }

Metadata for a bearer-token credential, without automatic OAuth refresh.

mcp_server_url: string

The HTTPS MCP server URL authorized by this credential.

minLength0
type: "static_bearer"

The type of the object. Always static_bearer.

EnvironmentVariable object { networking, secret_name, type }

Metadata for an HTTP credential used only in OpenAI-hosted environments. Sandbox code receives a placeholder. The proxy substitutes the secret for allowed HTTPS destinations on ports 443 and 8443. The real secret is not available to sandbox code for local computation and is never returned in this resource.

networking: CredentialNetworking

The destinations where the proxy can substitute the secret, subject to the environment network policy.

secret_name: string

The environment variable name that receives the placeholder in the sandbox.

minLength0
type: "environment_variable"

The type of the object. Always environment_variable.

CredentialAuthCreateParam = McpOauth { access_token, mcp_server_url, type, 2 more } or StaticBearer { token, mcp_server_url, type } or EnvironmentVariable { networking, secret_name, secret_value, type }

Authentication credentials for an MCP server or an OpenAI-hosted environment.

One of the following:
McpOauth object { access_token, mcp_server_url, type, 2 more }

An OAuth credential for an HTTPS MCP destination.

access_token: string

A write-only OAuth access token; never returned by credential resources.

minLength0
maxLength1048576
mcp_server_url: string

The HTTPS MCP server URL authorized by this credential.

minLength0
maxLength1048576
type: "mcp_oauth"

The type of the object. Always mcp_oauth.

expires_at: optional string or null

When the OAuth access token expires, as an RFC 3339 timestamp, if known.

minLength0
maxLength1048576
refresh: optional object { client_id, refresh_token, token_endpoint, 3 more } or null

Optional refresh configuration for an HTTPS OAuth token endpoint.

client_id: string

The OAuth client ID used when requesting a new access token.

minLength0
maxLength1048576
refresh_token: string

The refresh token to store. This secret is never returned in credential resources.

minLength0
maxLength1048576
token_endpoint: string

The HTTPS OAuth token endpoint used to exchange the refresh token for a new access token.

minLength0
maxLength1048576
token_endpoint_auth: McpOauthTokenEndpointAuthCreateParam

How the OAuth client authenticates to the token endpoint.

resource: optional string or null

The resource URI to send to the OAuth token endpoint during refresh, if required.

minLength0
maxLength1048576
scope: optional string or null

Space-separated OAuth scopes to request during refresh, if required.

minLength0
maxLength1048576
StaticBearer object { token, mcp_server_url, type }

A bearer token for an MCP server, without automatic OAuth refresh.

token: string

The bearer token to store. This secret is never returned in credential resources.

minLength0
maxLength1048576
mcp_server_url: string

The HTTPS MCP server URL authorized by this credential.

minLength0
maxLength1048576
type: "static_bearer"

The type of the object. Always static_bearer.

EnvironmentVariable object { networking, secret_name, secret_value, type }

An HTTP credential for OpenAI-hosted environments only. The sandbox receives an environment variable containing a placeholder, not the secret. Use the placeholder unchanged in outgoing requests. The egress proxy replaces the placeholder with the secret for allowed HTTPS destinations on ports 443 and 8443. Sandbox code cannot read the real secret or use it for local computation, such as signing a request.

networking: CredentialNetworkingParam

The destinations where the proxy can substitute this secret. The environment network policy must also allow them.

secret_name: string

The environment variable name that receives the placeholder, such as SERVICE_API_KEY. Use ASCII letters, digits, and underscores, starting with a letter or underscore. Names starting with CODEX_ and managed proxy or certificate variable names are reserved.

minLength1
maxLength1048576
secret_value: string

The write-only secret to store. Never returned in credential resources or supplied directly to sandbox code. Must be nonempty and must not contain carriage returns, newlines, or NUL bytes.

minLength1
maxLength1048576
type: "environment_variable"

The type of the object. Always environment_variable.

CredentialAuthRotateParam = McpOauth { type, access_token, expires_at, refresh } or StaticBearer { token, type } or EnvironmentVariable { secret_value, type }

Updates to a vault credential without changing its authentication method or destination configuration.

One of the following:
McpOauth object { type, access_token, expires_at, refresh }

Rotate an OAuth credential for an HTTPS MCP destination.

type: "mcp_oauth"

The type of the object. Always mcp_oauth.

access_token: optional string or null

A write-only replacement OAuth access token.

minLength0
maxLength1048576
expires_at: optional string or null

The replacement expiry as an RFC 3339 timestamp, or null to clear it. Omitting this field preserves the expiry unless a new access token is supplied, in which case the expiry is cleared.

minLength0
maxLength1048576
refresh: optional object { refresh_token, scope, token_endpoint_auth } or null

Optional write-only refresh-token and client-secret updates.

refresh_token: optional string or null

The replacement refresh token. Omit or pass null to keep the stored token. This secret is never returned in resources.

minLength0
maxLength1048576
scope: optional string or null

Replacement space-separated OAuth scopes for refresh requests. Omit to keep the scopes, or pass null to stop sending a scope parameter.

minLength0
maxLength1048576
token_endpoint_auth: optional McpOauthTokenEndpointAuthRotateParam or null

Client-secret updates for the existing token endpoint authentication method.

StaticBearer object { token, type }

Replace the bearer token for the credential’s MCP server.

token: string

The replacement bearer token. This secret is never returned in credential resources.

minLength0
maxLength1048576
type: "static_bearer"

The type of the object. Always static_bearer.

EnvironmentVariable object { secret_value, type }

Replace the secret for an OpenAI-hosted environment credential. The environment variable name and networking configuration remain unchanged.

secret_value: string

The write-only replacement secret. Never returned in credential resources or supplied directly to sandbox code. Must be nonempty and must not contain carriage returns, newlines, or NUL bytes.

minLength1
maxLength1048576
type: "environment_variable"

The type of the object. Always environment_variable.

CredentialDeleted object { id, deleted, object }

Confirmation that a vault credential was deleted.

id: string

The ID of the deleted credential.

minLength0
deleted: boolean

Whether the resource was deleted. Always true.

object: "vault.credential.deleted"

The object type. Always vault.credential.deleted.

CredentialNetworking = Unrestricted { type } or Limited { allowed_hosts, type }

Destination permissions for an environment-variable credential. These do not grant network access to the environment.

One of the following:
Unrestricted object { type }

Allows substitution for destinations permitted by the environment network policy. Requires environment.network.access to be restricted, with explicit allowed_domains.

type: "unrestricted"

The type of the object. Always unrestricted.

Limited object { allowed_hosts, type }

Allows substitution only for the listed hosts. The environment network policy must also allow these hosts.

allowed_hosts: array of string

The 1 to 16 distinct allowed hostnames or IPv4 addresses, normalized to lowercase. Entries contain no scheme, path, port, or wildcard. IPv6 addresses are not supported.

type: "limited"

The type of the object. Always limited.

CredentialNetworkingParam = Unrestricted { type } or Limited { allowed_hosts, type }

Destination permissions for an environment-variable credential. These do not grant network access to the environment.

One of the following:
Unrestricted object { type }

Allows substitution for destinations permitted by the environment network policy. Requires environment.network.access to be restricted, with explicit allowed_domains.

type: "unrestricted"

The type of the object. Always unrestricted.

Limited object { allowed_hosts, type }

Allows substitution only for the listed hosts. The environment network policy must also allow these hosts.

allowed_hosts: array of string

The 1 to 16 distinct allowed hostnames or IPv4 addresses, normalized to lowercase. Entries contain no scheme, path, port, or wildcard. IPv6 addresses are not supported.

type: "limited"

The type of the object. Always limited.

McpOauthTokenEndpointAuth = None { type } or ClientSecretBasic { type } or ClientSecretPost { type }

The client authentication method used for OAuth token refresh.

One of the following:
None object { type }

Sends the client ID without a client secret.

type: "none"

The type of the object. Always none.

ClientSecretBasic object { type }

Sends the client ID and secret using HTTP Basic authentication.

type: "client_secret_basic"

The type of the object. Always client_secret_basic.

ClientSecretPost object { type }

Sends the client ID and secret in the token request body.

type: "client_secret_post"

The type of the object. Always client_secret_post.

McpOauthTokenEndpointAuthCreateParam = None { type } or ClientSecretBasic { client_secret, type } or ClientSecretPost { client_secret, type }

Client authentication credentials for OAuth token refresh.

One of the following:
None object { type }

Sends the client ID without a client secret.

type: "none"

The type of the object. Always none.

ClientSecretBasic object { client_secret, type }

Sends the client ID and secret using HTTP Basic authentication.

client_secret: string

The OAuth client secret to store. Never returned in credential resources.

minLength0
maxLength1048576
type: "client_secret_basic"

The type of the object. Always client_secret_basic.

ClientSecretPost object { client_secret, type }

Sends the client ID and secret in the token request body.

client_secret: string

The OAuth client secret to store. Never returned in credential resources.

minLength0
maxLength1048576
type: "client_secret_post"

The type of the object. Always client_secret_post.

McpOauthTokenEndpointAuthRotateParam = ClientSecretBasic { type, client_secret } or ClientSecretPost { type, client_secret }

Client-secret updates that preserve the credential’s OAuth authentication method.

One of the following:
ClientSecretBasic object { type, client_secret }

Updates credentials sent using HTTP Basic authentication.

type: "client_secret_basic"

The type of the object. Always client_secret_basic.

client_secret: optional string or null

The replacement OAuth client secret. Omit or pass null to keep the stored secret. This secret is never returned in resources.

minLength0
maxLength1048576
ClientSecretPost object { type, client_secret }

Updates credentials sent in the token request body.

type: "client_secret_post"

The type of the object. Always client_secret_post.

client_secret: optional string or null

The replacement OAuth client secret. Omit or pass null to keep the stored secret. This secret is never returned in resources.

minLength0
maxLength1048576