@anthropic-ai/sdk
Version:
The official TypeScript library for the Anthropic API
328 lines (302 loc) • 11.2 kB
text/typescript
import { APIResource } from '../../../core/resource';
import * as BetaAPI from '../beta';
import { APIPromise } from '../../../core/api-promise';
import { PageCursor, type PageCursorParams, PagePromise } from '../../../core/pagination';
import { buildHeaders } from '../../../internal/headers';
import { RequestOptions } from '../../../internal/request-options';
import { startApiCallSpan } from '../../../internal/tracing';
import { path } from '../../../internal/utils/path';
export class Certificates extends APIResource {
/**
* The Tunnels API is in research preview. It requires the
* `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a
* deprecation period. It supersedes the Admin API endpoints at
* `/v1/organizations/tunnels`, which remain available during a migration window.
*
* Registers a public CA certificate on a tunnel. Anthropic verifies the gateway's
* server certificate against this CA when it terminates the inner TLS session. A
* tunnel holds at most two non-archived certificates.
*
* @example
* ```ts
* const betaTunnelCertificate =
* await client.beta.tunnels.certificates.create(
* 'tunnel_id',
* { ca_certificate_pem: 'ca_certificate_pem' },
* );
* ```
*/
create(
tunnelID: string,
params: CertificateCreateParams,
options?: RequestOptions,
): APIPromise<BetaTunnelCertificate> {
const { betas, workspace_id, ...body } = params;
return this._client.post(path`/v1/tunnels/${tunnelID}/certificates?beta=true`, {
body,
...options,
headers: buildHeaders([
{
'anthropic-beta': [...(betas ?? []), 'mcp-tunnels-2026-06-22'].toString(),
...(workspace_id != null ? { 'anthropic-workspace-id': workspace_id } : undefined),
},
options?.headers,
]),
__span: startApiCallSpan(this._client, 'anthropic.tunnels.certificates.create', options, {
route: '/v1/tunnels/{tunnel_id}/certificates',
attributes: { 'anthropic.tunnel.id': tunnelID },
createdIDAttribute: 'anthropic.tunnel.certificate.id',
}),
});
}
/**
* The Tunnels API is in research preview. It requires the
* `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a
* deprecation period. It supersedes the Admin API endpoints at
* `/v1/organizations/tunnels`, which remain available during a migration window.
*
* Fetches a tunnel certificate by ID.
*
* @example
* ```ts
* const betaTunnelCertificate =
* await client.beta.tunnels.certificates.retrieve(
* 'certificate_id',
* { tunnel_id: 'tunnel_id' },
* );
* ```
*/
retrieve(
certificateID: string,
params: CertificateRetrieveParams,
options?: RequestOptions,
): APIPromise<BetaTunnelCertificate> {
const { tunnel_id, betas, workspace_id } = params;
return this._client.get(path`/v1/tunnels/${tunnel_id}/certificates/${certificateID}?beta=true`, {
...options,
headers: buildHeaders([
{
'anthropic-beta': [...(betas ?? []), 'mcp-tunnels-2026-06-22'].toString(),
...(workspace_id != null ? { 'anthropic-workspace-id': workspace_id } : undefined),
},
options?.headers,
]),
__span: startApiCallSpan(this._client, 'anthropic.tunnels.certificates.retrieve', options, {
route: '/v1/tunnels/{tunnel_id}/certificates/{certificate_id}',
attributes: { 'anthropic.tunnel.id': tunnel_id, 'anthropic.tunnel.certificate.id': certificateID },
}),
});
}
/**
* The Tunnels API is in research preview. It requires the
* `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a
* deprecation period. It supersedes the Admin API endpoints at
* `/v1/organizations/tunnels`, which remain available during a migration window.
*
* Lists the certificates registered on a tunnel. Archived certificates are
* excluded unless include_archived is set.
*
* @example
* ```ts
* // Automatically fetches more pages as needed.
* for await (const betaTunnelCertificate of client.beta.tunnels.certificates.list(
* 'tunnel_id',
* )) {
* // ...
* }
* ```
*/
list(
tunnelID: string,
params: CertificateListParams | null | undefined = {},
options?: RequestOptions,
): PagePromise<BetaTunnelCertificatesPageCursor, BetaTunnelCertificate> {
const { betas, workspace_id, ...query } = params ?? {};
return this._client.getAPIList(
path`/v1/tunnels/${tunnelID}/certificates?beta=true`,
PageCursor<BetaTunnelCertificate>,
{
query,
...options,
headers: buildHeaders([
{
'anthropic-beta': [...(betas ?? []), 'mcp-tunnels-2026-06-22'].toString(),
...(workspace_id != null ? { 'anthropic-workspace-id': workspace_id } : undefined),
},
options?.headers,
]),
__span: startApiCallSpan(this._client, 'anthropic.tunnels.certificates.list', options, {
route: '/v1/tunnels/{tunnel_id}/certificates',
queryParams: ['include_archived', 'limit', 'page'],
attributes: { 'anthropic.tunnel.id': tunnelID },
}),
},
);
}
/**
* The Tunnels API is in research preview. It requires the
* `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a
* deprecation period. It supersedes the Admin API endpoints at
* `/v1/organizations/tunnels`, which remain available during a migration window.
*
* Archives a tunnel certificate, removing it from the set Anthropic trusts for the
* 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.
*
* @example
* ```ts
* const betaTunnelCertificate =
* await client.beta.tunnels.certificates.archive(
* 'certificate_id',
* { tunnel_id: 'tunnel_id' },
* );
* ```
*/
archive(
certificateID: string,
params: CertificateArchiveParams,
options?: RequestOptions,
): APIPromise<BetaTunnelCertificate> {
const { tunnel_id, betas, workspace_id } = params;
return this._client.post(path`/v1/tunnels/${tunnel_id}/certificates/${certificateID}/archive?beta=true`, {
...options,
headers: buildHeaders([
{
'anthropic-beta': [...(betas ?? []), 'mcp-tunnels-2026-06-22'].toString(),
...(workspace_id != null ? { 'anthropic-workspace-id': workspace_id } : undefined),
},
options?.headers,
]),
__span: startApiCallSpan(this._client, 'anthropic.tunnels.certificates.archive', options, {
route: '/v1/tunnels/{tunnel_id}/certificates/{certificate_id}/archive',
attributes: { 'anthropic.tunnel.id': tunnel_id, 'anthropic.tunnel.certificate.id': certificateID },
}),
});
}
}
export type BetaTunnelCertificatesPageCursor = PageCursor<BetaTunnelCertificate>;
/**
* A CA certificate attached to a tunnel.
*/
export interface BetaTunnelCertificate {
/**
* Unique identifier for the certificate, prefixed with `tcrt_`.
*/
id: string;
/**
* RFC 3339 datetime string indicating when the certificate was archived. Null if
* it is still in the trusted set.
*/
archived_at: string | null;
/**
* RFC 3339 datetime string indicating when the certificate was registered.
*/
created_at: string;
/**
* RFC 3339 datetime string indicating when the certificate expires, or `null` if
* it does not expire.
*/
expires_at: string | null;
/**
* Lowercase hex SHA-256 fingerprint of the certificate's DER encoding.
*/
fingerprint: string;
/**
* ID of the tunnel the certificate is registered against.
*/
tunnel_id: string;
type: 'tunnel_certificate';
}
export interface CertificateCreateParams {
/**
* Body param: PEM-encoded X.509 CA certificate. Must contain exactly one
* certificate and no private-key material. Maximum 8KB.
*/
ca_certificate_pem: string;
/**
* Header param: This endpoint is in beta: requests must send
* `mcp-tunnels-2026-06-22` in this header.
*/
betas?: Array<BetaAPI.AnthropicBeta>;
/**
* Header param: Optional header to select the Workspace for this request. The
* value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`).
*
* Only needed for credentials that can act on more than one Workspace. A
* credential that belongs to a specific Workspace may omit it; if sent, it must
* match that Workspace.
*/
workspace_id?: string;
}
export interface CertificateRetrieveParams {
/**
* Path param: ID of the tunnel (`tnl_...`).
*/
tunnel_id: string;
/**
* Header param: This endpoint is in beta: requests must send
* `mcp-tunnels-2026-06-22` in this header.
*/
betas?: Array<BetaAPI.AnthropicBeta>;
/**
* Header param: Optional header to select the Workspace for this request. The
* value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`).
*
* Only needed for credentials that can act on more than one Workspace. A
* credential that belongs to a specific Workspace may omit it; if sent, it must
* match that Workspace.
*/
workspace_id?: string;
}
export interface CertificateListParams extends PageCursorParams {
/**
* Query param: Whether to include archived certificates in the results. Defaults
* to false.
*/
include_archived?: boolean;
/**
* Header param: This endpoint is in beta: requests must send
* `mcp-tunnels-2026-06-22` in this header.
*/
betas?: Array<BetaAPI.AnthropicBeta>;
/**
* Header param: Optional header to select the Workspace for this request. The
* value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`).
*
* Only needed for credentials that can act on more than one Workspace. A
* credential that belongs to a specific Workspace may omit it; if sent, it must
* match that Workspace.
*/
workspace_id?: string;
}
export interface CertificateArchiveParams {
/**
* Path param: ID of the tunnel (`tnl_...`).
*/
tunnel_id: string;
/**
* Header param: This endpoint is in beta: requests must send
* `mcp-tunnels-2026-06-22` in this header.
*/
betas?: Array<BetaAPI.AnthropicBeta>;
/**
* Header param: Optional header to select the Workspace for this request. The
* value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`).
*
* Only needed for credentials that can act on more than one Workspace. A
* credential that belongs to a specific Workspace may omit it; if sent, it must
* match that Workspace.
*/
workspace_id?: string;
}
export declare namespace Certificates {
export {
type BetaTunnelCertificate as BetaTunnelCertificate,
type BetaTunnelCertificatesPageCursor as BetaTunnelCertificatesPageCursor,
type CertificateCreateParams as CertificateCreateParams,
type CertificateRetrieveParams as CertificateRetrieveParams,
type CertificateListParams as CertificateListParams,
type CertificateArchiveParams as CertificateArchiveParams,
};
}