> ## 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.

# List listener certificates

> Return attached certificates using the same public Certificate contract as GET /v1/certificates, including domains, status, expiry, challenges, faults, and public PEMs. The certificates collection includes finite pagination metadata. Compare each id with listener.default_certificate.id to identify the default. Requires loadbalancer:ListListenerCertificates on the listener CRN; no certificate-service permission is required. Private keys and attachment UUIDs are never returned.

<Info>
  Requires the IAM action **`loadbalancer:ListListenerCertificates`**. See [LOADBALANCER permissions](/loadbalancer/permissions) for the full list, what each one covers, and an example policy.
</Info>


## OpenAPI

````yaml /api-reference/specs/loadbalancer.yaml get /v1/load-balancers/{id}/listeners/{listener_id}/certificates
openapi: 3.0.3
info:
  title: Basaltic Load Balancer API
  version: 1.0.0
  description: >
    Request relationships accept syntax-classified references resolved within
    the caller account and region.

    Floating IP references accept UUID or CRN only; IP targets stay literal.

    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:
  - BearerAuth: []
paths:
  /v1/load-balancers/{id}/listeners/{listener_id}/certificates:
    get:
      tags:
        - Load Balancers
      summary: List listener certificates
      description: >-
        Return attached certificates using the same public Certificate contract
        as GET /v1/certificates, including domains, status, expiry, challenges,
        faults, and public PEMs. The certificates collection includes finite
        pagination metadata. Compare each id with
        listener.default_certificate.id to identify the default. Requires
        loadbalancer:ListListenerCertificates on the listener CRN; no
        certificate-service permission is required. Private keys and attachment
        UUIDs are never returned.
      operationId: listListenerCertificates
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: 4e1f8c2a-9b3d-4f6e-8a1c-2d5e7f9a0b3c
        - name: listener_id
          in: path
          required: true
          schema:
            type: string
            example: e1f2a3b4-c5d6-4789-e0f1-a2b3c4d5e6f7
      responses:
        '200':
          description: Attached certificate resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListenerCertificateListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    ListenerCertificateListResponse:
      type: object
      required:
        - certificates
        - meta
      properties:
        certificates:
          type: array
          items:
            $ref: '#/components/schemas/Certificate'
          example:
            - id: 550e8400-e29b-41d4-a716-446655440012
              crn: crn:certificate::my-account:certificate/prod-web
              name: prod-web
              domains:
                - www.example.com
              status: active
              source: uploaded
              key_algorithm: ecdsa-p256
              challenges: []
              certificate_pem: |
                -----BEGIN CERTIFICATE-----
                MIIDdzCCAl+gAwIBAgIEAaH...
                -----END CERTIFICATE-----
              chain_pem: |
                -----BEGIN CERTIFICATE-----
                MIIEFzCCAv+gAwIBAgIEBb2...
                -----END CERTIFICATE-----
              issued_at: '2026-10-01T09:30:00Z'
              expires_at: '2026-12-30T09:30:00Z'
              faults: []
              tags: {}
        meta:
          allOf:
            - $ref: '#/components/schemas/PaginationMeta'
          example:
            limit: 1
            has_more: false
    Certificate:
      type: object
      required:
        - faults
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        crn:
          type: string
          readOnly: true
          description: >-
            Name-based, so an IAM policy can wildcard a naming convention
            (`crn:certificate::my-account:certificate/prod-*`). The region slot
            is empty for compatibility; certificate storage and KMS material are
            regional.
          example: crn:certificate::my-account:certificate/prod-frontend
        name:
          description: >-
            Resource names must not start with the literal crn: prefix or be
            UUIDs (canonical, compact, braced, or urn:uuid: forms, in either
            case).
          type: string
          example: prod-frontend
        domains:
          type: array
          items:
            type: string
          example:
            - example.com
            - www.example.com
            - api.example.com
        status:
          $ref: '#/components/schemas/CertificateStatus'
        source:
          $ref: '#/components/schemas/CertificateSource'
        key_algorithm:
          $ref: '#/components/schemas/CertificateKeyAlgorithm'
        challenges:
          type: array
          items:
            $ref: '#/components/schemas/CertificateChallenge'
          description: |
            Per-domain CNAME delegation state — one entry per domain on
            the cert. While status=pending_dns issuance waits for every
            challenge's `verified` to flip true; use `expected_cname` and
            `our_dns` to tell which records need to be added at the
            registrar.
        certificate_pem:
          type: string
          description: PEM-encoded leaf certificate. Empty until active.
          example: |
            -----BEGIN CERTIFICATE-----
            MIIDdzCCAl+gAwIBAgIEAaH...
            -----END CERTIFICATE-----
        chain_pem:
          type: string
          description: PEM-encoded intermediate chain.
          example: |
            -----BEGIN CERTIFICATE-----
            MIIEFzCCAv+gAwIBAgIEBb2...
            -----END CERTIFICATE-----
        fingerprint:
          type: string
          readOnly: true
          description: >
            Hex SHA-256 of the leaf's DER — the certificate's material version.
            Changes on every rotation; consumers use it to know when to re-fetch
            material and to verify they fetched the intended generation. Empty
            until the cert has a leaf.
          example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
        issued_at:
          type: string
          format: date-time
          readOnly: true
          example: '2026-01-15T09:30:00Z'
        expires_at:
          type: string
          format: date-time
          readOnly: true
          example: '2026-04-15T09:30:00Z'
        faults:
          type: array
          items:
            $ref: '#/components/schemas/Fault'
          description: >
            Active faults, ordered newest first. Empty when healthy. Renewal

            failures are warnings while valid certificate material still serves.

            Codes: CERTIFICATE_ISSUANCE_START_FAILED (issuance could not be

            scheduled), CERTIFICATE_ISSUANCE_FAILED (the signing request
            failed),

            CERTIFICATE_RENEWAL_FAILED (renewal did not complete; a warning
            while

            valid material is still serving, an error once it has expired),

            CERTIFICATE_REVOCATION_FAILED (revocation did not complete).
        tags:
          $ref: '#/components/schemas/Tags'
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
          description: Total number of items
          example: 150
        limit:
          type: integer
          description: Number of items per page
          example: 20
        marker:
          type: string
          description: >-
            Opaque cursor for the next page. Pass it back as the `marker` query
            parameter; treat it as a token, not a value to parse.
          example: 550e8400-e29b-41d4-a716-446655440000
        has_more:
          type: boolean
          description: Whether there are more items
          example: true
    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
            params:
              type: object
              additionalProperties: true
              description: >-
                Optional non-sensitive values for interpolation of localized
                errors, keyed by error code. Never present for server errors.
              example:
                instances: 2
                pools: 0
            request_id:
              type: string
              format: uuid
              description: Request ID for debugging
              example: 550e8400-e29b-41d4-a716-446655440000
    CertificateStatus:
      description: Error if and only if an active error-severity fault exists.
      type: string
      enum:
        - pending_dns
        - pending
        - active
        - error
        - expired
        - revoked
      example: active
    CertificateSource:
      type: string
      enum:
        - acme
        - uploaded
      example: acme
    CertificateKeyAlgorithm:
      type: string
      enum:
        - ecdsa-p256
        - ecdsa-p384
        - rsa-2048
        - rsa-4096
      default: ecdsa-p256
    CertificateChallenge:
      type: object
      required:
        - faults
      properties:
        domain:
          type: string
          description: The cert SAN this challenge belongs to (as the customer wrote it).
          example: '*.example.com'
        cname_record_name:
          type: string
          description: |
            Full LHS of the CNAME record the customer needs to add. For
            wildcard SANs this is the parent name
            (`_acme-challenge.example.com.`), not the literal SAN —
            wildcards validate at their parent under RFC 8555 §8.4.
          example: _acme-challenge.example.com.
        expected_cname:
          type: string
          description: |
            Target FQDN (RHS of the CNAME). Hosted in the platform's
            validation zone, where the per-order TXT is published during
            issuance.
          example: a1b2c3d4e5f6g7h8.acme.basaltic.cloud.
        our_dns:
          type: boolean
          description: |
            True when the domain is hosted on the platform DNS service and
            the CNAME was created automatically. False means the customer
            owns the zone and must add the CNAME at their registrar.
          example: true
        verified:
          type: boolean
          description: |
            True once the CNAME has resolved to expected_cname; cert
            issuance only proceeds when every challenge is verified.
          example: true
        verified_at:
          type: string
          format: date-time
          readOnly: true
          example: '2026-01-15T09:28:00Z'
        faults:
          type: array
          items:
            $ref: '#/components/schemas/Fault'
          description: >
            Active verification warnings only; empty when healthy. Successful

            verification resolves verification faults while retaining history.

            verified records a successful observation and remains true if a
            later

            renewal observes a DNS failure. A CNAME mismatch records

            CERTIFICATE_DNS_VERIFICATION_FAILED as a warning; verified does not

            move. Internal history uses the parent CRN

            followed by /challenge/<stored-uuid>; no separate endpoint is
            exposed.
    Fault:
      type: object
      required:
        - code
        - severity
        - message
        - details
        - first_at
        - last_at
        - occurrences
      properties:
        code:
          type: string
          description: Stable machine-readable code owned by the reporting operation.
          example: BACKUP_FAILED
        severity:
          type: string
          enum:
            - error
            - warning
        message:
          type: string
          example: Backup upload failed.
        details:
          type: object
          nullable: true
          additionalProperties: true
          description: Structured context; legacy strings are preserved in legacy_text.
        first_at:
          type: string
          format: date-time
          description: First observation in this active occurrence series.
        last_at:
          type: string
          format: date-time
          description: Latest observation in this active occurrence series.
        occurrences:
          type: integer
          minimum: 1
          example: 1
    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
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_ERROR
              message: An internal error occurred
              request_id: 550e8400-e29b-41d4-a716-446655440000
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        An OAuth 2.0 bearer token, sent as `Authorization: Bearer <token>`.
        This is the recommended way to authenticate.

        Get one by exchanging a service account's access key pair at
        `POST /v1/oauth/token` with `grant_type=client_credentials`. It is the
        standard client-credentials grant, so any OAuth-aware library will
        obtain and refresh it for you.

        ```
        curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
          https://iam.basaltic.sh/v1/oauth/token
        ```

        Tokens last an hour by default. The same access key pair is separately
        your AWS SigV4 credential for the S3-compatible object endpoint, which
        speaks nothing else.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.