SPB Git
spboucher.ai

Repository Public

spbdoc-api

tunnel_certificates.md 19.4 KB

# title: Tunnel Certificates url: https://platform.claude.com/docs/en/api/beta/organization/mcp_tunnels/tunnel_certificates

# Tunnel Certificates

# Create Tunnel Certificate

POST /v1/organizations/tunnels/{tunnel_id}/certificates

Deprecated

Deprecated. This Admin API endpoint is superseded by /v1/tunnels on the Claude API and will be removed after a migration window. New integrations should use /v1/tunnels with the anthropic-beta: mcp-tunnels-2026-06-22 header and a WIF token carrying the workspace:manage_tunnels scope. Existing integrations continue to work with the mcp-tunnels-2026-05-19 header and org:manage_tunnels scope during the migration window.

Register a public CA certificate for the tunnel.

Anthropic verifies the gateway's server certificate against this CA when it terminates the inner TLS session. The PEM body must contain exactly one X.509 certificate and no private-key material. A tunnel holds at most two non-archived certificates.

# Path parameters

  • tunnel_id: string

    ID of the Tunnel.

# Headers

  • "anthropic-beta": array of AnthropicBeta

    This endpoint is in beta: requests must send mcp-tunnels-2026-05-19 in this header.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more

      • "message-batches-2024-09-24"

      • "prompt-caching-2024-07-31"

      • "computer-use-2024-10-22"

      • "computer-use-2025-01-24"

      • "pdfs-2024-09-25"

      • "token-counting-2024-11-01"

      • "token-efficient-tools-2025-02-19"

      • "output-128k-2025-02-19"

      • "files-api-2025-04-14"

      • "mcp-client-2025-04-04"

      • "mcp-client-2025-11-20"

      • "dev-full-thinking-2025-05-14"

      • "interleaved-thinking-2025-05-14"

      • "code-execution-2025-05-22"

      • "extended-cache-ttl-2025-04-11"

      • "context-1m-2025-08-07"

      • "context-management-2025-06-27"

      • "model-context-window-exceeded-2025-08-26"

      • "skills-2025-10-02"

      • "fast-mode-2026-02-01"

      • "output-300k-2026-03-24"

      • "user-profiles-2026-03-24"

      • "user-profiles-2026-08-18"

      • "user-profiles-2026-09-04"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

      • "dreaming-2026-04-21"

      • "thinking-token-count-2026-05-13"

      • "server-side-fallback-2026-06-01"

      • "server-side-fallback-2026-07-01"

      • "fallback-credit-2026-06-01"

      • "fallback-credit-2026-07-01"

      • "agent-memory-2026-07-22"

      • "mid-conversation-tool-changes-2026-07-01"

      • "compact-2026-01-12"

      • "computer-use-2025-11-24"

      • "mcp-tunnels-2026-06-22"

      • "structured-outputs-2025-11-13"

      • "task-budgets-2026-03-13"

      • "thinking-display-updates-2026-08-18"

      • "ce-user-management-2026-07-13"

      • "mid-conversation-output-config-2026-07-01"

      • "thinking-binding-controls-2026-08-01"

      • "mid-conversation-system-clear-at-2026-08-21"

      • "compact-2026-09-04"

# Body parameters

  • ca_certificate_pem: string

    PEM-encoded X.509 CA certificate. Must contain exactly one certificate and no private-key material.

    maxLength: 8192

# Returns

  • BetaOrganizationTunnelCertificate object

    • type: "tunnel_certificate"

      Object type. Always tunnel_certificate for Tunnel Certificates.

      default: tunnel_certificate

    • id: string

      ID of the Tunnel Certificate.

    • archived_at: string or null

      RFC 3339 datetime string indicating when the certificate was archived, or null if it is not archived.

      format: date-time

    • created_at: string

      RFC 3339 datetime string indicating when the certificate was registered.

      format: date-time

    • expires_at: string or null

      RFC 3339 datetime string indicating when the certificate expires, or null if it does not expire.

      format: date-time

    • fingerprint: string

      The certificate's SHA-256 fingerprint, as a lowercase hex string.

    • tunnel_id: string

      ID of the Tunnel this certificate is registered against.

# Example

bash
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/certificates \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: mcp-tunnels-2026-05-19' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "ca_certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIBexampleEXAMPLEexampleEXAMPLEexampleEXAMPLEexampleEXAMPLEexa\n...illustrative placeholder, not a real certificate...\n-----END CERTIFICATE-----\n"
        }'

# Response (200)

json
{
  "id": "tcrt_01JmWq4ZxnBvR7tKpY2sLdH9",
  "archived_at": "2024-11-01T23:59:27.427722Z",
  "created_at": "2024-10-30T23:58:27.427722Z",
  "expires_at": "2024-10-30T23:58:27.427722Z",
  "fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "tunnel_id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
  "type": "tunnel_certificate"
}

# List Tunnel Certificates

GET /v1/organizations/tunnels/{tunnel_id}/certificates

Deprecated

Deprecated. This Admin API endpoint is superseded by /v1/tunnels on the Claude API and will be removed after a migration window. New integrations should use /v1/tunnels with the anthropic-beta: mcp-tunnels-2026-06-22 header and a WIF token carrying the workspace:manage_tunnels scope. Existing integrations continue to work with the mcp-tunnels-2026-05-19 header and org:manage_tunnels scope during the migration window.

List the certificates registered on a tunnel.

Archived certificates are excluded unless include_archived is set.

# Path parameters

  • tunnel_id: string

    ID of the Tunnel.

# Query parameters

  • include_archived: optional boolean

    Include archived certificates in the results. Archived certificates are excluded by default.

    default: false

  • limit: optional number

    Maximum number of certificates to return.

    default: 20, maximum: 1000, minimum: 1

  • page: optional string

    A tunnel has at most two active certificates, so this list is not paginated.

# Headers

  • "anthropic-beta": array of AnthropicBeta

    This endpoint is in beta: requests must send mcp-tunnels-2026-05-19 in this header.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more

      • "message-batches-2024-09-24"

      • "prompt-caching-2024-07-31"

      • "computer-use-2024-10-22"

      • "computer-use-2025-01-24"

      • "pdfs-2024-09-25"

      • "token-counting-2024-11-01"

      • "token-efficient-tools-2025-02-19"

      • "output-128k-2025-02-19"

      • "files-api-2025-04-14"

      • "mcp-client-2025-04-04"

      • "mcp-client-2025-11-20"

      • "dev-full-thinking-2025-05-14"

      • "interleaved-thinking-2025-05-14"

      • "code-execution-2025-05-22"

      • "extended-cache-ttl-2025-04-11"

      • "context-1m-2025-08-07"

      • "context-management-2025-06-27"

      • "model-context-window-exceeded-2025-08-26"

      • "skills-2025-10-02"

      • "fast-mode-2026-02-01"

      • "output-300k-2026-03-24"

      • "user-profiles-2026-03-24"

      • "user-profiles-2026-08-18"

      • "user-profiles-2026-09-04"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

      • "dreaming-2026-04-21"

      • "thinking-token-count-2026-05-13"

      • "server-side-fallback-2026-06-01"

      • "server-side-fallback-2026-07-01"

      • "fallback-credit-2026-06-01"

      • "fallback-credit-2026-07-01"

      • "agent-memory-2026-07-22"

      • "mid-conversation-tool-changes-2026-07-01"

      • "compact-2026-01-12"

      • "computer-use-2025-11-24"

      • "mcp-tunnels-2026-06-22"

      • "structured-outputs-2025-11-13"

      • "task-budgets-2026-03-13"

      • "thinking-display-updates-2026-08-18"

      • "ce-user-management-2026-07-13"

      • "mid-conversation-output-config-2026-07-01"

      • "thinking-binding-controls-2026-08-01"

      • "mid-conversation-system-clear-at-2026-08-21"

      • "compact-2026-09-04"

# Returns

  • data: array of BetaOrganizationTunnelCertificate

    • type: "tunnel_certificate"

      Object type. Always tunnel_certificate for Tunnel Certificates.

      default: tunnel_certificate

    • id: string

      ID of the Tunnel Certificate.

    • archived_at: string or null

      RFC 3339 datetime string indicating when the certificate was archived, or null if it is not archived.

      format: date-time

    • created_at: string

      RFC 3339 datetime string indicating when the certificate was registered.

      format: date-time

    • expires_at: string or null

      RFC 3339 datetime string indicating when the certificate expires, or null if it does not expire.

      format: date-time

    • fingerprint: string

      The certificate's SHA-256 fingerprint, as a lowercase hex string.

    • tunnel_id: string

      ID of the Tunnel this certificate is registered against.

  • next_page: string or null

    Opaque cursor for the next page, or null if there are no more results.

# Example

bash
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/certificates \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: mcp-tunnels-2026-05-19' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

# Response (200)

json
{
  "data": [
    {
      "id": "tcrt_01JmWq4ZxnBvR7tKpY2sLdH9",
      "archived_at": "2024-11-01T23:59:27.427722Z",
      "created_at": "2024-10-30T23:58:27.427722Z",
      "expires_at": "2024-10-30T23:58:27.427722Z",
      "fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "tunnel_id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
      "type": "tunnel_certificate"
    }
  ],
  "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}

# Get Tunnel Certificate

GET /v1/organizations/tunnels/{tunnel_id}/certificates/{certificate_id}

Deprecated

Deprecated. This Admin API endpoint is superseded by /v1/tunnels on the Claude API and will be removed after a migration window. New integrations should use /v1/tunnels with the anthropic-beta: mcp-tunnels-2026-06-22 header and a WIF token carrying the workspace:manage_tunnels scope. Existing integrations continue to work with the mcp-tunnels-2026-05-19 header and org:manage_tunnels scope during the migration window.

Retrieve a single certificate registered on a tunnel by ID.

# Path parameters

  • tunnel_id: string

    ID of the Tunnel.

  • certificate_id: string

    ID of the Tunnel Certificate.

# Headers

  • "anthropic-beta": array of AnthropicBeta

    This endpoint is in beta: requests must send mcp-tunnels-2026-05-19 in this header.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more

      • "message-batches-2024-09-24"

      • "prompt-caching-2024-07-31"

      • "computer-use-2024-10-22"

      • "computer-use-2025-01-24"

      • "pdfs-2024-09-25"

      • "token-counting-2024-11-01"

      • "token-efficient-tools-2025-02-19"

      • "output-128k-2025-02-19"

      • "files-api-2025-04-14"

      • "mcp-client-2025-04-04"

      • "mcp-client-2025-11-20"

      • "dev-full-thinking-2025-05-14"

      • "interleaved-thinking-2025-05-14"

      • "code-execution-2025-05-22"

      • "extended-cache-ttl-2025-04-11"

      • "context-1m-2025-08-07"

      • "context-management-2025-06-27"

      • "model-context-window-exceeded-2025-08-26"

      • "skills-2025-10-02"

      • "fast-mode-2026-02-01"

      • "output-300k-2026-03-24"

      • "user-profiles-2026-03-24"

      • "user-profiles-2026-08-18"

      • "user-profiles-2026-09-04"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

      • "dreaming-2026-04-21"

      • "thinking-token-count-2026-05-13"

      • "server-side-fallback-2026-06-01"

      • "server-side-fallback-2026-07-01"

      • "fallback-credit-2026-06-01"

      • "fallback-credit-2026-07-01"

      • "agent-memory-2026-07-22"

      • "mid-conversation-tool-changes-2026-07-01"

      • "compact-2026-01-12"

      • "computer-use-2025-11-24"

      • "mcp-tunnels-2026-06-22"

      • "structured-outputs-2025-11-13"

      • "task-budgets-2026-03-13"

      • "thinking-display-updates-2026-08-18"

      • "ce-user-management-2026-07-13"

      • "mid-conversation-output-config-2026-07-01"

      • "thinking-binding-controls-2026-08-01"

      • "mid-conversation-system-clear-at-2026-08-21"

      • "compact-2026-09-04"

# Returns

  • BetaOrganizationTunnelCertificate object

    • type: "tunnel_certificate"

      Object type. Always tunnel_certificate for Tunnel Certificates.

      default: tunnel_certificate

    • id: string

      ID of the Tunnel Certificate.

    • archived_at: string or null

      RFC 3339 datetime string indicating when the certificate was archived, or null if it is not archived.

      format: date-time

    • created_at: string

      RFC 3339 datetime string indicating when the certificate was registered.

      format: date-time

    • expires_at: string or null

      RFC 3339 datetime string indicating when the certificate expires, or null if it does not expire.

      format: date-time

    • fingerprint: string

      The certificate's SHA-256 fingerprint, as a lowercase hex string.

    • tunnel_id: string

      ID of the Tunnel this certificate is registered against.

# Example

bash
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/certificates/$CERTIFICATE_ID \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: mcp-tunnels-2026-05-19' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

# Response (200)

json
{
  "id": "tcrt_01JmWq4ZxnBvR7tKpY2sLdH9",
  "archived_at": "2024-11-01T23:59:27.427722Z",
  "created_at": "2024-10-30T23:58:27.427722Z",
  "expires_at": "2024-10-30T23:58:27.427722Z",
  "fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "tunnel_id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
  "type": "tunnel_certificate"
}

# Archive Tunnel Certificate

POST /v1/organizations/tunnels/{tunnel_id}/certificates/{certificate_id}/archive

Deprecated

Deprecated. This Admin API endpoint is superseded by /v1/tunnels on the Claude API and will be removed after a migration window. New integrations should use /v1/tunnels with the anthropic-beta: mcp-tunnels-2026-06-22 header and a WIF token carrying the workspace:manage_tunnels scope. Existing integrations continue to work with the mcp-tunnels-2026-05-19 header and org:manage_tunnels scope during the migration window.

Archive a certificate, removing it from the set Anthropic trusts for this tunnel.

The certificate record is retained. Archiving the last non-archived certificate is permitted; the tunnel rejects MCP traffic until a new certificate is added.

# Path parameters

  • tunnel_id: string

    ID of the Tunnel.

  • certificate_id: string

    ID of the Tunnel Certificate.

# Headers

  • "anthropic-beta": array of AnthropicBeta

    This endpoint is in beta: requests must send mcp-tunnels-2026-05-19 in this header.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more

      • "message-batches-2024-09-24"

      • "prompt-caching-2024-07-31"

      • "computer-use-2024-10-22"

      • "computer-use-2025-01-24"

      • "pdfs-2024-09-25"

      • "token-counting-2024-11-01"

      • "token-efficient-tools-2025-02-19"

      • "output-128k-2025-02-19"

      • "files-api-2025-04-14"

      • "mcp-client-2025-04-04"

      • "mcp-client-2025-11-20"

      • "dev-full-thinking-2025-05-14"

      • "interleaved-thinking-2025-05-14"

      • "code-execution-2025-05-22"

      • "extended-cache-ttl-2025-04-11"

      • "context-1m-2025-08-07"

      • "context-management-2025-06-27"

      • "model-context-window-exceeded-2025-08-26"

      • "skills-2025-10-02"

      • "fast-mode-2026-02-01"

      • "output-300k-2026-03-24"

      • "user-profiles-2026-03-24"

      • "user-profiles-2026-08-18"

      • "user-profiles-2026-09-04"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

      • "dreaming-2026-04-21"

      • "thinking-token-count-2026-05-13"

      • "server-side-fallback-2026-06-01"

      • "server-side-fallback-2026-07-01"

      • "fallback-credit-2026-06-01"

      • "fallback-credit-2026-07-01"

      • "agent-memory-2026-07-22"

      • "mid-conversation-tool-changes-2026-07-01"

      • "compact-2026-01-12"

      • "computer-use-2025-11-24"

      • "mcp-tunnels-2026-06-22"

      • "structured-outputs-2025-11-13"

      • "task-budgets-2026-03-13"

      • "thinking-display-updates-2026-08-18"

      • "ce-user-management-2026-07-13"

      • "mid-conversation-output-config-2026-07-01"

      • "thinking-binding-controls-2026-08-01"

      • "mid-conversation-system-clear-at-2026-08-21"

      • "compact-2026-09-04"

# Returns

  • BetaOrganizationTunnelCertificate object

    • type: "tunnel_certificate"

      Object type. Always tunnel_certificate for Tunnel Certificates.

      default: tunnel_certificate

    • id: string

      ID of the Tunnel Certificate.

    • archived_at: string or null

      RFC 3339 datetime string indicating when the certificate was archived, or null if it is not archived.

      format: date-time

    • created_at: string

      RFC 3339 datetime string indicating when the certificate was registered.

      format: date-time

    • expires_at: string or null

      RFC 3339 datetime string indicating when the certificate expires, or null if it does not expire.

      format: date-time

    • fingerprint: string

      The certificate's SHA-256 fingerprint, as a lowercase hex string.

    • tunnel_id: string

      ID of the Tunnel this certificate is registered against.

# Example

bash
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/certificates/$CERTIFICATE_ID/archive \
    -X POST \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: mcp-tunnels-2026-05-19' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

# Response (200)

json
{
  "id": "tcrt_01JmWq4ZxnBvR7tKpY2sLdH9",
  "archived_at": "2024-11-01T23:59:27.427722Z",
  "created_at": "2024-10-30T23:58:27.427722Z",
  "expires_at": "2024-10-30T23:58:27.427722Z",
  "fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "tunnel_id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
  "type": "tunnel_certificate"
}

# Domain types

# Beta Organization Tunnel Certificate

  • BetaOrganizationTunnelCertificate object

    • type: "tunnel_certificate"

      Object type. Always tunnel_certificate for Tunnel Certificates.

      default: tunnel_certificate

    • id: string

      ID of the Tunnel Certificate.

    • archived_at: string or null

      RFC 3339 datetime string indicating when the certificate was archived, or null if it is not archived.

      format: date-time

    • created_at: string

      RFC 3339 datetime string indicating when the certificate was registered.

      format: date-time

    • expires_at: string or null

      RFC 3339 datetime string indicating when the certificate expires, or null if it does not expire.

      format: date-time

    • fingerprint: string

      The certificate's SHA-256 fingerprint, as a lowercase hex string.

    • tunnel_id: string

      ID of the Tunnel this certificate is registered against.

Files main
Menu

Theme
↑↓navigate ↵open escclose /⌘Kanywhere