Create Credential

Prerequisites

Endpoint and authentication configured. For details, see Overview and authentication.

Endpoint

POST /vaults/{vault_id}/credentials

Request body

Field	Required	Type	Description
`auth`	Yes	object	Authentication information, always of the environment_variable type. See auth type below
`display_name`	No	string	Human-readable name of the Credential, max 255 characters
`metadata`	No	object	Custom key-value pairs for business metadata

auth type

The auth field currently supports only the environment_variable type, which injects as an environment variable into sessions.

Field	Required	Type	Description
`type`	Yes	string	Always `environment_variable`
`secret_name`	Yes	string	Environment variable name; immutable after creation
`secret_value`	Yes	string	Environment variable value; write-only, never returned in responses
`networking`	Yes	object	Network policy that restricts real-key substitution to requests sent to the specified hosts
`networking.allowed_hosts`	Yes	array	List of hosts allowed for real-key substitution. Supports `.example.com` wildcard subdomains, up to 10 entries. Set `` to apply to all hosts
`injection_location`	Yes	object	Injection location that marks where the secret is written into the request. Currently only the Authorization header is supported; writing into the request body is not yet supported
`injection_location.header`	No	boolean	Whether to write into the Authorization header (Bearer format)

Request example

curl -X POST "$AGENTSTUDIO_URL/vaults/vlt_xxx/credentials" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Third-party API key",
    "auth": {
      "type": "environment_variable",
      "secret_name": "API_KEY",
      "secret_value": "sk-xxxx",
      "networking": {
        "allowed_hosts": [
          "api.example.com",
          "*.example.com"
        ]
      },
      "injection_location": {
        "header": true
      }
    }
  }'

Response example

{
  "id": "cred_xxx",
  "type": "credential",
  "vault_id": "vlt_xxx",
  "display_name": "Third-party API key",
  "auth": {
    "type": "environment_variable",
    "secret_name": "API_KEY",
    "networking": {
      "allowed_hosts": [
        "api.example.com",
        "*.example.com"
      ]
    },
    "injection_location": {
      "header": true
    }
  },
  "metadata": {},
  "archived_at": null,
  "created_at": "2026-07-10T08:00:00Z",
  "updated_at": "2026-07-10T08:00:00Z",
  "request_id": "req_xxx"
}

Response fields

Field	Type	Description
`id`	string	Credential ID, format `cred_xxx`
`type`	string	Always `credential`
`vault_id`	string	Vault ID that the Credential belongs to
`display_name`	string	Human-readable name of the Credential
`auth`	object	Authentication information with sensitive values masked (e.g. `secret_value` is not returned)
`auth.type`	string	Auth type; currently only `environment_variable`
`auth.secret_name`	string	Environment variable name
`auth.networking`	object	Network policy
`auth.networking.allowed_hosts`	array	List of hosts allowed for real-key substitution
`auth.injection_location`	object	Injection location. Currently only the Authorization header is supported; writing into the request body is not yet supported
`auth.injection_location.header`	boolean	Whether to write into the Authorization header
`metadata`	object	Custom key-value pairs
`archived_at`	string \| null	Archive timestamp; `null` if not archived
`created_at`	string	Creation time, ISO 8601
`updated_at`	string	Last update time, ISO 8601
`request_id`	string	Unique request identifier

Error codes

HTTP status	Error code	Description
400	`InvalidParameter`	Required parameter missing or invalid
401	`InvalidApiKey`	Invalid API key provided

​Prerequisites

​Endpoint

​Request body

​auth type

​Request example

​Response example

​Response fields

​Error codes