Skip to main content

Create credential

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 parameters

vault_id string (required)Parent vault ID. Treat it as an opaque ID

Request body

name string (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
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
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 example

curl -sS -X POST "$BASE_URL/vaults/vlt_xxx/credentials" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "crm-token",
    "metadata": {"team": "support"},
    "auth": {
      "type": "environment_variable",
      "secret_name": "CRM_TOKEN",
      "secret_value": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "networking": {
        "type": "limited",
        "allowed_hosts": ["api.example.com"]
      }
    }
  }'
auth.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 fields

201, 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.
type stringAuthentication type, fixed as environment_variablesecret_name stringEnvironment variable namenetworking objectTarget domain settings.
type stringNetwork access type, limited or unrestrictedallowed_hosts arrayDomains or IPv4 addresses allowed for limited

Response example

{
  "id": "vcrd_xxx",
  "object": "vault.credential",
  "vault_id": "vlt_xxx",
  "name": "crm-token",
  "created_at": 1793941200,
  "updated_at": 1793941200,
  "metadata": {"team": "support"},
  "auth": {
    "type": "environment_variable",
    "secret_name": "CRM_TOKEN",
    "networking": {
      "type": "limited",
      "allowed_hosts": ["api.example.com"]
    }
  }
}

Error codes

For the error response structure, see Errors.
HTTP statusError type / codeSolution
400invalid_request_error / unknown_parameterThe request contains an unknown field, such as auth.injection_location
400invalid_request_error / invalid_typeFix the field type as described
400invalid_request_error / invalid_request_errorname, metadata, auth, or a host setting does not meet the requirements
401authentication_error / invalid_api_keySend a valid Authorization: Bearer $DASHSCOPE_API_KEY header
404not_found_error / not_found_errorThe parent vault does not exist, is deleted, or belongs to another workspace
409conflict_error / conflict_errorRetry later. If it keeps failing, submit a ticket with x-request-id
500server_error / server_errorRetry later. If it keeps failing, submit a ticket with x-request-id