Copy

Description

Creates a Credential in the specified Vault. Sensitive authentication fields are never echoed in the response.

Path

POST /api/v1/forward/vaults/{id}/credentials

Request headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT or SAT>`
`Idempotency-Key`	No	Optional idempotency key for create requests. The same key can only be used for the same request.
`Content-Type`	Yes	`application/json`

Path parameters

Parameter	Type	Required	Description
`id`	string	Yes	Vault ID.

Request body

Field	Type	Required	Description
`auth`	object	Yes	Credential authentication information. Supports `static_bearer`, `mcp_oauth`, and `environment_variable`; responses include only redacted, non-secret fields.
`display_name`	string	No	Compatibility field. It is not currently persisted, and Forward responses always return an empty string.
`metadata`	object	No	Metadata object. `created_by` is reserved and must not be supplied (supplying it returns 400).

`auth` fields

static_bearer:

Field	Type	Required	Description
`type`	string	Yes	Must be `static_bearer`.
`mcp_server_url`	string	Yes	MCP Server URL.
`token`	string	Yes	Bearer token. Write-only and never returned in responses.

mcp_oauth:

Field	Type	Required	Description
`type`	string	Yes	Must be `mcp_oauth`.
`mcp_server_url`	string	Yes	MCP Server URL.
`access_token`	string	Yes	OAuth access token. Write-only and never returned in responses.
`expires_at`	string	No	Access token expiration time in RFC 3339 format.
`refresh`	object	No	OAuth refresh configuration. Secret fields are never returned in responses.

environment_variable:

Field	Type	Required	Description
`type`	string	Yes	Must be `environment_variable`.
`secret_name`	string	Yes	Environment variable name. Must match `[A-Za-z_][A-Za-z0-9_]*`.
`secret_value`	string	Yes	Environment variable value. Write-only and never returned in responses.

auth.protocol is not a Forward Credential request field and has no effect if provided.

Example request

{
  "auth": {
    "type": "static_bearer",
    "mcp_server_url": "https://mcp.example.com",
    "token": "secret_token"
  },
  "display_name": "example-mcp",
  "metadata": {
    "source": "console"
  }
}

Example response

HTTP 201 Created

{
  "id": "vcred_xxx",
  "type": "vault_credential",
  "vault_id": "vault_xxx",
  "auth": {
    "type": "static_bearer",
    "mcp_server_url": "https://mcp.example.com"
  },
  "display_name": "",
  "metadata": {
    "source": "console"
  },
  "created_at": "2026-07-23T10:00:00Z",
  "updated_at": "2026-07-23T10:00:00Z"
}

Response fields

Field	Type	Description
`id`	string	Credential ID.
`type`	string	Always `vault_credential`.
`vault_id`	string	Parent Vault ID.
`auth`	object	Redacted authentication data.
`display_name`	string	Currently always an empty string.
`metadata`	object	Credential Metadata.
`created_at`	string	Creation time in RFC 3339 format.
`updated_at`	string	Last update time in RFC 3339 format.

Errors

HTTP	Type	Trigger
400	`invalid_request_error`	The request body, path parameters, or query parameters are invalid.
400	`invalid_request_error`	If the reserved key `created_by` is supplied, `message` is `metadata key "created_by" is reserved`, identifying the invalid field.
401	`authentication_error`	The authentication token is missing or invalid.
403	`permission_error`	The caller cannot access this resource.
404	`not_found_error`	The Vault does not exist or is not visible.
409	`conflict_error`	The resource state, references, or idempotency key conflict.
500/502/503	`api_error`	Forward or a dependent service failed.

​Description

​Path

​Request headers

​Path parameters

​Request body

​auth fields

​Example request

​Example response

​Response fields

​Errors