--- title: "Create a vault credential" method: POST path: "/vaults/{vault_id}/credentials" tags: ["Vaults"] --- # Create a vault credential `POST /vaults/{vault_id}/credentials` Creates a vault credential. Secret values are write-only and are never returned. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults). ## Path parameters - `vault_id` string, required ## Request body - CreateVaultCredentialParams — Parameters for storing a credential for an MCP server or an OpenAI-hosted environment. - `name` string, required — The name is trimmed before storage. It must contain 1 to 256 UTF-8 bytes after trimming. - `auth` union, required — Authentication credentials for an MCP server or an OpenAI-hosted environment. - object — An OAuth credential for an HTTPS MCP destination. - `type` 'mcp_oauth', required — The type of the object. Always `mcp_oauth`. - `mcp_server_url` string, required — The HTTPS MCP server URL authorized by this credential. - `access_token` string, required — A write-only OAuth access token; never returned by credential resources. - `expires_at` string, nullable — When the OAuth access token expires, as an RFC 3339 timestamp, if known. - `refresh` CreateMcpOauthRefreshParam — Configuration for refreshing the access token of an MCP OAuth credential. - `token_endpoint` string, required — The HTTPS OAuth token endpoint used to exchange the refresh token for a new access token. - `client_id` string, required — The OAuth client ID used when requesting a new access token. - `resource` string, nullable — The resource URI to send to the OAuth token endpoint during refresh, if required. - `scope` string, nullable — Space-separated OAuth scopes to request during refresh, if required. - `refresh_token` string, required — The refresh token to store. This secret is never returned in credential resources. - `token_endpoint_auth` union, required — Client authentication credentials for OAuth token refresh. - object — Sends the client ID without a client secret. - `type` 'none', required — The type of the object. Always `none`. - object — Sends the client ID and secret using HTTP Basic authentication. - `type` 'client_secret_basic', required — The type of the object. Always `client_secret_basic`. - `client_secret` string, required — The OAuth client secret to store. Never returned in credential resources. - object — Sends the client ID and secret in the token request body. - `type` 'client_secret_post', required — The type of the object. Always `client_secret_post`. - `client_secret` string, required — The OAuth client secret to store. Never returned in credential resources. - object — A bearer token for an MCP server, without automatic OAuth refresh. - `type` 'static_bearer', required — The type of the object. Always `static_bearer`. - `mcp_server_url` string, required — The HTTPS MCP server URL authorized by this credential. - `token` string, required — The bearer token to store. This secret is never returned in credential resources. - object — 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. - `type` 'environment_variable', required — The type of the object. Always `environment_variable`. - `secret_name` string, required — 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. - `secret_value` string, required — 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. - `networking` union, required — Destination permissions for an environment-variable credential. These do not grant network access to the environment. - object — Allows substitution for destinations permitted by the environment network policy. Requires `environment.network.access` to be `restricted`, with explicit `allowed_domains`. - `type` 'unrestricted', required — The type of the object. Always `unrestricted`. - object — Allows substitution only for the listed hosts. The environment network policy must also allow these hosts. - `type` 'limited', required — The type of the object. Always `limited`. - `allowed_hosts` string[], required — 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. - `metadata` object — Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. Defaults to an empty map. ## Response `201` The created vault credential without secret values. - VaultCredentialResource — Metadata for a stored credential. Secret values are never returned. - `id` string, required — The ID of the credential. - `object` 'vault.credential', required — The object type. Always `vault.credential`. - `vault_id` string, required — The ID of the vault containing this credential. - `name` string, required — The human-readable name of the credential. - `auth` union, required — The authentication configuration of a vault credential, excluding secrets. - object — Public metadata for an OAuth credential; tokens and client secrets are never returned. - `type` 'mcp_oauth', required — The type of the object. Always `mcp_oauth`. - `mcp_server_url` string, required — The HTTPS MCP server URL authorized by this credential. - `expires_at` string, nullable, required — When the OAuth access token expires, as an RFC 3339 timestamp, if known. - `refresh` McpOauthRefreshResource, required — Configuration used to refresh an MCP OAuth access token, excluding secret values. - `token_endpoint` string, required — The HTTPS OAuth token endpoint used for refresh. - `client_id` string, required — The OAuth client ID used when requesting a new access token. - `resource` string, nullable, required — The resource URI sent to the OAuth token endpoint during refresh, if configured. - `scope` string, nullable, required — Space-separated OAuth scopes requested during refresh, if configured. - `token_endpoint_auth` union, required — The client authentication method used for OAuth token refresh. - object — Sends the client ID without a client secret. - `type` 'none', required — The type of the object. Always `none`. - object — Sends the client ID and secret using HTTP Basic authentication. - `type` 'client_secret_basic', required — The type of the object. Always `client_secret_basic`. - object — Sends the client ID and secret in the token request body. - `type` 'client_secret_post', required — The type of the object. Always `client_secret_post`. - object — Metadata for a bearer-token credential, without automatic OAuth refresh. - `type` 'static_bearer', required — The type of the object. Always `static_bearer`. - `mcp_server_url` string, required — The HTTPS MCP server URL authorized by this credential. - object — 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. - `type` 'environment_variable', required — The type of the object. Always `environment_variable`. - `secret_name` string, required — The environment variable name that receives the placeholder in the sandbox. - `networking` union, required — Destination permissions for an environment-variable credential. These do not grant network access to the environment. - object — Allows substitution for destinations permitted by the environment network policy. Requires `environment.network.access` to be `restricted`, with explicit `allowed_domains`. - `type` 'unrestricted', required — The type of the object. Always `unrestricted`. - object — Allows substitution only for the listed hosts. The environment network policy must also allow these hosts. - `type` 'limited', required — The type of the object. Always `limited`. - `allowed_hosts` string[], required — 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. - `metadata` object, required — Application-defined key-value pairs associated with this credential. - `created_at` integer, required — The Unix timestamp, in seconds, when the credential was created. - `updated_at` integer, required — The Unix timestamp, in seconds, when the credential was last updated. ## Other responses - `400` — The request was invalid. - `401` — Authentication or project context was missing. - `403` — The API key lacks the required management permission. - `404` — The requested vault or credential was not found. - `409` — The request conflicted with the current vault state. - `500` — An internal error occurred. - `503` — The service is temporarily unavailable. ## Changes - **2026-09-22** `d1cbc7a20461` — 2 info - added the new optional request property `metadata` - added the required property `metadata` to the response with the `201` status - **2026-09-18** `ae9b7322bc4f` — 1 breaking, 3 info - added `#/components/schemas/VaultCredentialAuthResourceEnvironmentVariable` to the `auth` response property `oneOf` list for the response status `201` - added `environment_variable` discriminator mapping keys to the `auth` request property - added `#/components/schemas/CreateVaultCredentialAuthParamEnvironmentVariable` to the `auth` request property `oneOf` list - added `environment_variable` discriminator mapping keys to the `auth` response property for the response status `201` - **2026-09-10** `f2dae1a9aced` — 1 info - endpoint added [Change history](https://skmtc.dev/openai/apis/openapi/changes/vaults/:vault_id/credentials/post.md) --- [API](https://skmtc.dev/openai/apis/openapi.md) · [All operations](https://skmtc.dev/openai/apis/openapi/llms.txt) · [OpenAPI document](https://skmtc.dev/openai/apis/openapi/revisions/222f167a2327?raw)