> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # Attach an additional certificate to an HTTPS listener > Multi-SNI: the listener routes per-connection by matching the client's SNI against each attached cert's SAN. Pass is_default=true to make this the fallback cert (used when no SNI matches or the client omits SNI entirely); whatever was default before is demoted in the same transaction. ## OpenAPI ````yaml /api-reference/specs/loadbalancer.yaml post /v1/load-balancers/{id}/listeners/{listener_id}/certificates openapi: 3.0.3 info: title: Basaltic Load Balancer API version: 1.0.0 description: | Managed load balancers: listeners, target pools, health checks and the TLS certificates a listener terminates. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://loadbalancer.{region}.basaltic.sh description: Regional API endpoint variables: region: default: sa-saopaulo-1 description: Region code security: - SignatureAuth: [] paths: /v1/load-balancers/{id}/listeners/{listener_id}/certificates: post: tags: - Load Balancers summary: Attach an additional certificate to an HTTPS listener description: | Multi-SNI: the listener routes per-connection by matching the client's SNI against each attached cert's SAN. Pass is_default=true to make this the fallback cert (used when no SNI matches or the client omits SNI entirely); whatever was default before is demoted in the same transaction. operationId: attachListenerCertificate parameters: - $ref: '#/components/parameters/IdempotencyKey' - name: id in: path required: true schema: type: string format: uuid example: 4e1f8c2a-9b3d-4f6e-8a1c-2d5e7f9a0b3c - name: listener_id in: path required: true schema: type: string format: uuid example: e1f2a3b4-c5d6-4789-e0f1-a2b3c4d5e6f7 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AttachListenerCertificateRequest' responses: '201': description: Attached content: application/json: schema: $ref: '#/components/schemas/ListenerResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' components: parameters: IdempotencyKey: name: Idempotency-Key in: header description: >- Optional client-generated key that makes a create replay-safe. Retrying a request with the same key returns the original outcome verbatim instead of creating a duplicate resource. Reusing a key with a different request body is rejected (422); a request whose key is still being processed returns 409. Records are honored for 24 hours. Use a UUID or similarly unique token. required: false schema: type: string maxLength: 255 example: 550e8400-e29b-41d4-a716-446655440000 schemas: AttachListenerCertificateRequest: type: object required: - certificate_crn - certificate_pem - private_key_pem properties: certificate_crn: type: string example: crn:certificate::my-account:certificate/prod-web certificate_pem: type: string example: | -----BEGIN CERTIFICATE----- MIIDdzCCAl+gAwIBAgIE... -----END CERTIFICATE----- chain_pem: type: string example: | -----BEGIN CERTIFICATE----- MIIDQTCCAimgAwIBAgIT... -----END CERTIFICATE----- private_key_pem: type: string example: | -----BEGIN PRIVATE KEY----- MIIEvQIBADANBgkqhkiG... -----END PRIVATE KEY----- is_default: type: boolean default: false example: true description: | When true, demote whatever's currently default and promote this cert in the same transaction. ListenerResponse: type: object properties: listener: $ref: '#/components/schemas/Listener' Listener: type: object required: - id - load_balancer_id - protocol - port - exposure - tags - created_at - updated_at properties: id: type: string format: uuid example: e1f2a3b4-c5d6-4789-e0f1-a2b3c4d5e6f7 load_balancer_id: type: string format: uuid example: 4e1f8c2a-9b3d-4f6e-8a1c-2d5e7f9a0b3c protocol: type: string enum: - http - https - tcp - udp example: https port: type: integer minimum: 1 maximum: 65535 example: 443 certificates: type: array description: | HTTPS listeners only. One entry per attached certificate; the right cert is picked per-connection by matching the client's SNI against each cert's SAN. The entry flagged is_default serves traffic that doesn't match any other SNI (or clients that omit SNI). PEM material is NOT echoed — the listener stores its own copy fetched at attach time. items: $ref: '#/components/schemas/ListenerCertificate' default_target_group_id: type: string format: uuid example: b8c9d0e1-f2a3-4456-b7c8-d9e0f1a2b3c4 exposure: type: string enum: - public_only - private_only - both example: both description: | Which LB addresses this listener binds. 'public_only' and 'both' require the LB to carry a floating IP; if the FIP is detached later, the listener is dropped until a FIP is re-attached or exposure is flipped to private_only. tags: $ref: '#/components/schemas/Tags' created_at: type: string format: date-time example: '2026-01-15T09:30:00Z' updated_at: type: string format: date-time example: '2026-01-15T09:30:00Z' Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Error code identifying the type of error example: INVALID_INPUT message: type: string description: Human-readable error message example: Invalid request parameters request_id: type: string format: uuid description: Request ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 ListenerCertificate: type: object required: - id - certificate_crn - is_default - created_at - updated_at properties: id: type: string format: uuid example: f2a3b4c5-d6e7-4890-f1a2-b3c4d5e6f7a8 certificate_crn: type: string example: crn:certificate::my-account:certificate/prod-web is_default: type: boolean example: true created_at: type: string format: date-time example: '2026-01-15T09:30:00Z' updated_at: type: string format: date-time example: '2026-01-15T09:30:00Z' Tags: type: object additionalProperties: type: string example: environment: production team: backend responses: BadRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_INPUT message: Invalid request parameters request_id: 550e8400-e29b-41d4-a716-446655440000 Unauthorized: description: Authentication required or token invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Authentication required request_id: 550e8400-e29b-41d4-a716-446655440000 Forbidden: description: Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ACCESS_DENIED message: You don't have permission to perform this action request_id: 550e8400-e29b-41d4-a716-446655440000 NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Resource not found request_id: 550e8400-e29b-41d4-a716-446655440000 Conflict: description: Resource conflict (e.g., already exists, invalid state) content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: CONFLICT message: Resource with this name already exists request_id: 550e8400-e29b-41d4-a716-446655440000 UnprocessableEntity: description: | The request is well-formed but cannot be processed as sent. On the operations that accept `Idempotency-Key` this is the key-reuse case: the key was first seen with a different request payload, so replaying the stored outcome would answer a question the caller did not ask. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: IDEMPOTENCY_KEY_REUSED message: >- This Idempotency-Key was already used with a different request payload request_id: 550e8400-e29b-41d4-a716-446655440000 securitySchemes: SignatureAuth: type: apiKey in: header name: Authorization description: > Request signing with an access key issued to a service account. An HMAC-SHA256 over a canonical form of the request, close to AWS SigV4. The `basaltic` CLI signs for you. Send `Authorization`, `X-Date` (UTC, `YYYYMMDDTHHMMSSZ`) and `X-Nonce` (random per request); add `X-Content-Sha256` to bind a body, and `X-Amz-Security-Token` when using temporary credentials. ``` Authorization: BASALTIC-HMAC-SHA256 Credential=///basaltic/basaltic_request, SignedHeaders=host;x-date;x-nonce, Signature= ``` `` is the region code you are calling, or `global` for the global services. A signature is valid for 5 minutes from `X-Date`, and mutating requests are replay-guarded on the nonce. **Full signing procedure, including a working implementation:** https://docs.basaltic.sh/authentication ## Rate limits There is no global request budget. A limit applies only where an operation documents a `429`, and that operation says what it counts. Those responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and, on a `429`, `Retry-After` — read them rather than hard-coding a number. Retrying before `Retry-After` is refused and extends the window. Everything else is bounded by quota, not by request rate. ````