Create a credential in a vault. Only the environment_variable type is supported.
Endpoint
POST /vaults/{vault_id}/credentials
Paths are relative to the Base URL. Send Authorization: Bearer $DASHSCOPE_API_KEY on every request. For authentication details, see Authentication.
Path parametersvault_idstring (required)Parent vault ID. Treat it as an opaque IDRequest bodynamestring (required)Display name, not the environment variable name. 1–256 bytes after trimmingmetadata object (optional)Metadata, string key-value pairs, up to 16 items; key 1–64 characters, value up to 512 characters. null returns 400auth object (required)Authentication settings. Missing or null returns 400
Properties type string (required)Authentication type, fixed as environment_variablesecret_name string (required)Environment variable name injected into the environment. Must start with a letter and contain only letters, digits, and underscores; cannot start with a reserved prefixsecret_value string (required)Secret value, 1–1048576 characters; cannot contain line breaks or NUL. Write-only and never returnednetworking object (required)Target domain settings. Missing or null returns 400
Properties type string (required)Network access type, limited or unrestrictedallowed_hosts array (conditional)Domains or IPv4 addresses allowed to use the credential, 1–16 items. Except for the special value *, each item is an exact domain or IPv4 address; protocols, ports, paths, IPv6, and wildcard patterns such as *.example.com are not supported. Include * in the array to apply to all target hosts. Except for the special value *, a domain must contain at least two labels, each label up to 63 characters, and the total length must not exceed 253 characters. Values must be unique after lowercasing | Request exampleauth.injection_location is not a public input and returns 400 if sent.unrestricted credentials do not specify their own target domain list; when mounted to an Agents API environment, the environment must set network.access="restricted" and provide a non-empty, valid allowed_domains. When the credential is limited and allowed_hosts includes *, it applies to outbound requests to all target hosts; for security, we recommend setting network.access to restricted and providing a non-empty allowed_domains as described in Create an environment. |
Response fields201, returns a credential: The response does not return secret_value, the key identifier, or injection_location.id stringCredential IDobject stringCredential object type, fixed as vault.credentialvault_id stringParent vault IDname stringDisplay namecreated_at integerCreation time in Unix secondsupdated_at integerLast update time in Unix secondsmetadata objectMetadata, string key-value pairs; {} when not setauth objectAuthentication settings.
Properties type stringAuthentication type, fixed as environment_variablesecret_name stringEnvironment variable namenetworking objectTarget domain settings.
Properties type stringNetwork access type, limited or unrestrictedallowed_hosts arrayDomains or IPv4 addresses allowed for limited | Response example |
Error codes
For the error response structure, see Errors.
| HTTP status | Error type / code | Solution |
|---|---|---|
400 | invalid_request_error / unknown_parameter | The request contains an unknown field, such as auth.injection_location |
400 | invalid_request_error / invalid_type | Fix the field type as described |
400 | invalid_request_error / invalid_request_error | name, metadata, auth, or a host setting does not meet the requirements |
401 | authentication_error / invalid_api_key | Send a valid Authorization: Bearer $DASHSCOPE_API_KEY header |
404 | not_found_error / not_found_error | The parent vault does not exist, is deleted, or belongs to another workspace |
409 | conflict_error / conflict_error | Retry later. If it keeps failing, submit a ticket with x-request-id |
500 | server_error / server_error | Retry later. If it keeps failing, submit a ticket with x-request-id |