Create a credential

POST /api/v1/cloud/vaults/{vault_id}/credentials Adds a new MCP server credential to the specified vault.

Path parameters

Parameter	Type	Required	Description
`vault_id`	string	Yes	Vault unique identifier

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer $QODER_ACCESS_TOKEN`
`Content-Type`	Yes	`application/json`

Request body

Field	Type	Required	Description
`auth`	object	Yes	Credential authentication details. See Credential auth object
`display_name`	string	No	Accepted for compatibility; currently returned as `null` and not persisted
`metadata`	object	No	Custom metadata stored with the credential; defaults to `{}`

Example requests

Static Bearer

curl -X POST https://api.qoder.com/api/v1/cloud/vaults/vault_019e3bb940277f0db05ab74291acf6ef/credentials \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auth": {
      "type": "static_bearer",
      "mcp_server_url": "https://example.com/mcp-stream",
      "token": "your-access-token"
    },
    "metadata": {"team":"docs"}
  }'

Import an MCP OAuth token

Use this request when you already hold the OAuth tokens. For interactive browser authorization, use Start MCP OAuth instead.

curl -X POST https://api.qoder.com/api/v1/cloud/vaults/vault_019e3bb940277f0db05ab74291acf6ef/credentials \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auth": {
      "type": "mcp_oauth",
      "mcp_server_url": "https://mcp.example.com/mcp",
      "access_token": "oauth-access-token",
      "expires_at": "2026-08-16T08:00:00Z",
      "refresh": {
        "client_id": "oauth-client-id",
        "refresh_token": "oauth-refresh-token",
        "token_endpoint": "https://auth.example.com/oauth/token",
        "token_endpoint_auth": {
          "type": "client_secret_basic",
          "client_secret": "oauth-client-secret"
        },
        "resource": "https://mcp.example.com/mcp",
        "scope": "mcp.read mcp.write"
      }
    },
    "metadata": {"team":"docs"}
  }'

Example response

HTTP 200 OK

{
  "id": "vcred_019e3bb98877759e862750b495c1fce8",
  "type": "vault_credential",
  "vault_id": "vault_019e3bb940277f0db05ab74291acf6ef",
  "auth": {
    "type": "static_bearer",
    "mcp_server_url": "https://example.com/mcp-stream"
  },
  "display_name": null,
  "metadata": {
    "team": "docs"
  },
  "archived_at": null,
  "created_at": "2026-05-18T15:34:35.387093Z",
  "updated_at": "2026-05-18T15:34:35.387093Z"
}

An imported mcp_oauth response is sanitized in the same way:

{
  "id": "vcred_019e3bb98877759e862750b495c1fce8",
  "type": "vault_credential",
  "vault_id": "vault_019e3bb940277f0db05ab74291acf6ef",
  "auth": {
    "type": "mcp_oauth",
    "mcp_server_url": "https://mcp.example.com/mcp",
    "expires_at": "2026-08-16T08:00:00Z",
    "refresh": {
      "client_id": "oauth-client-id",
      "token_endpoint": "https://auth.example.com/oauth/token",
      "token_endpoint_auth": {"type": "client_secret_basic"},
      "resource": "https://mcp.example.com/mcp",
      "scope": "mcp.read mcp.write"
    }
  },
  "display_name": null,
  "metadata": {"team":"docs"},
  "archived_at": null,
  "created_at": "2026-05-18T15:34:35.387093Z",
  "updated_at": "2026-05-18T15:34:35.387093Z"
}

Response fields

Field	Type	Description
`id`	string	Credential unique identifier with the `vcred_` prefix
`type`	string	Always `"vault_credential"`
`vault_id`	string	Owning Vault ID
`auth`	object	Sanitized authentication details; secrets are never returned
`display_name`	null	Currently always `null`
`metadata`	object	Custom metadata object stored with the credential; defaults to `{}`
`archived_at`	string \| null	Archive time, or `null` when active
`created_at`	string	Creation time (ISO 8601)
`updated_at`	string	Last update time (ISO 8601)

Errors

HTTP	Type	Trigger
400	`invalid_request_error`	Missing `auth`, invalid credential type, missing required auth fields, or invalid `metadata`
401	`TOKEN_INVALID`	Missing or invalid authentication token
404	`not_found_error`	Vault does not exist or is not accessible
409	`conflict_error`	Vault is archived, vault reached the active credential limit, or a duplicate active MCP credential exists

Notes

The response does not return credential secrets, including token, access_token, refresh_token, or client_secret.
protocol is not part of the nested auth request. Credential matching uses mcp_server_url.
A vault can hold up to 20 active credentials.
Credentials are active immediately after creation.

See Errors for the full error envelope.

Authenticate with vaults

Store and inject secrets safely into agent sessions.

​Path parameters

​Headers

​Request body

​Example requests

​Static Bearer

​Import an MCP OAuth token

​Example response

​Response fields

​Errors

​Notes

​Related