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

# Crear certificado

> Crear un nuevo certificado. Por defecto a la emisión ACME; establecer `source=uploaded` para almacenar el material PEM suministrado por el cliente directamente.

Para fuente ACME: devuelve 202 con estado pending_dns y una entrada `challenges` por dominio normalizado, incluyendo `cname_record_name`, `expected_cname` y `our_dns`. Utilice estos campos directamente desde la respuesta de creación para configurar DNS. La planificación de desafíos se completa antes de que se acepte la creación; un error de planificación rechaza la solicitud sin guardar un certificado o un plan de desafío parcial.

Cuando `our_dns=true`, el CNAME se crea automáticamente durante la emisión asíncrona. De lo contrario, publique `cname_record_name CNAME
expected_cname` en su proveedor de DNS. Los comodines se validan en su nombre principal; un vértice y su comodín comparten el mismo CNAME. Consulta GET /v1/certificates/{certificate_id} para ver el progreso. El certificado se activa una vez que se verifica cada desafío y se completa la emisión.

Para fuente cargada: devuelve 201 con estado activo.


<Info>
  Requiere la acción de IAM **`certificate:CreateCertificate`**. Consulte [permisos de certificados](/certificate/permissions) para obtener la lista completa, lo que cubre cada uno y un ejemplo de directiva.
</Info>


## OpenAPI

````yaml /es/api-reference/specs/certificate.yaml post /v1/certificates
openapi: 3.0.3
info:
  title: API de certificado de Basaltic
  version: 1.0.0
  description: >
    Certificados TLS para escuchas de balanceador de carga y puntos finales de
    plataforma: emitir, inspeccionar, recuperar material y revocar. Los nombres
    son inmutables y únicos dentro de una cuenta. Enumerar por nombre exacto o
    CRN; las rutas de recursos usan UUID.
  contact:
    name: Basaltic Support
    email: ping@basaltic.sh
  license:
    name: Proprietary
    url: https://basaltic.sh/terms
servers:
  - url: https://certificate.{region}.basaltic.sh
    description: Punto final de API regional
    variables:
      region:
        default: sa-saopaulo-1
        description: Código de región
security:
  - BearerAuth: []
paths:
  /v1/certificates:
    post:
      tags:
        - Certificates
      summary: Crear certificado
      description: >
        Crear un nuevo certificado. Por defecto a la emisión ACME; establecer
        `source=uploaded` para almacenar el material PEM suministrado por el
        cliente directamente.


        Para fuente ACME: devuelve 202 con estado pending_dns y una entrada
        `challenges` por dominio normalizado, incluyendo `cname_record_name`,
        `expected_cname` y `our_dns`. Utilice estos campos directamente desde la
        respuesta de creación para configurar DNS. La planificación de desafíos
        se completa antes de que se acepte la creación; un error de
        planificación rechaza la solicitud sin guardar un certificado o un plan
        de desafío parcial.


        Cuando `our_dns=true`, el CNAME se crea automáticamente durante la
        emisión asíncrona. De lo contrario, publique `cname_record_name CNAME

        expected_cname` en su proveedor de DNS. Los comodines se validan en su
        nombre principal; un vértice y su comodín comparten el mismo CNAME.
        Consulta GET /v1/certificates/{certificate_id} para ver el progreso. El
        certificado se activa una vez que se verifica cada desafío y se completa
        la emisión.


        Para fuente cargada: devuelve 201 con estado activo.
      operationId: createCertificate
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CertificateIssueRequest'
      responses:
        '201':
          description: Certificado cargado almacenado (source=uploaded)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateResponse'
        '202':
          description: >-
            Emisión iniciada (fuente=acme). El estado es pending_dns y los
            desafíos contienen el plan de delegación DNS completo, listo para
            configurar.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Nombre del certificado ya en uso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - BearerAuth: []
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      description: >-
        Clave opcional generada por el cliente que hace que una creación sea
        segura para la reproducción. Al volver a intentar una solicitud con la
        misma clave, se devuelve el resultado original literalmente en lugar de
        crear un recurso duplicado. Se rechaza la reutilización de una clave con
        un cuerpo de solicitud diferente (422); una solicitud cuya clave todavía
        se está procesando devuelve 409. Los registros se mantienen durante 24
        horas. Usa un UUID o un token único similar.
      required: false
      schema:
        type: string
        maxLength: 255
      example: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    CertificateIssueRequest:
      type: object
      required:
        - name
        - domains
      properties:
        name:
          type: string
          pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,253}$
          description: >-
            Único por cuenta. Superficies en el CRN
            (`crn:certificate::<account>:certificate/<name>`), por lo que debe
            ser URL-safe — letras, dígitos, punto, guion, subrayado. Los nombres
            de los recursos no deben comenzar con el prefijo literal crn: ni ser
            UUID (en cualquier caso, en las formas canónica, compacta, entre
            corchetes o urn:uuid:).
          example: prod-frontend
        domains:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 100
          description: >
            Limitado a 100 para mantenerse dentro de los límites por pedido de
            la autoridad de certificación.
          example:
            - example.com
            - www.example.com
            - api.example.com
        key_algorithm:
          $ref: '#/components/schemas/CertificateKeyAlgorithm'
        source:
          $ref: '#/components/schemas/CertificateSource'
          description: >
            Por defecto, "acme" — emitido por la CA de la plataforma. Establezca
            "uploaded" para almacenar el material PEM suministrado por el
            cliente; certificate_pem + private_key_pem deben ser proporcionados.
        certificate_pem:
          type: string
          description: >-
            Certificado de hoja codificado PEM. Requerido cuando
            source=uploaded.
          example: |
            -----BEGIN CERTIFICATE-----
            MIIDdzCCAl+gAwIBAgIEAaH...
            -----END CERTIFICATE-----
        chain_pem:
          type: string
          description: >-
            Cadena intermedia codificada con PEM (opcional cuando
            source=uploaded).
          example: |
            -----BEGIN CERTIFICATE-----
            MIIEFzCCAv+gAwIBAgIEBb2...
            -----END CERTIFICATE-----
        private_key_pem:
          type: string
          description: Clave privada codificada con PEM. Requerido cuando source=uploaded.
          example: |
            -----BEGIN PRIVATE KEY-----
            MIGHAgEAMBMGByqGSM49AgEG...
            -----END PRIVATE KEY-----
        tags:
          $ref: '#/components/schemas/Tags'
    CertificateResponse:
      type: object
      properties:
        certificate:
          $ref: '#/components/schemas/Certificate'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              description: Código de error que identifica el tipo de error
              example: INVALID_INPUT
            message:
              type: string
              description: Mensaje de error legible por el ser humano
              example: Invalid request parameters
            params:
              type: object
              additionalProperties: true
              description: >-
                Valores no sensibles opcionales para la interpolación de errores
                localizados, codificados por código de error. Nunca presente por
                errores del servidor.
              example:
                instances: 2
                pools: 0
            request_id:
              type: string
              format: uuid
              description: Solicitar ID para depuración
              example: 550e8400-e29b-41d4-a716-446655440000
    CertificateKeyAlgorithm:
      type: string
      enum:
        - ecdsa-p256
        - ecdsa-p384
        - rsa-2048
        - rsa-4096
      default: ecdsa-p256
    CertificateSource:
      type: string
      enum:
        - acme
        - uploaded
      example: acme
    Tags:
      type: object
      additionalProperties:
        type: string
      example:
        environment: production
        team: backend
    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: >-
            Basado en nombre, por lo que una política de IAM puede usar comodín
            en una convención de nombres
            (`crn:certificate::my-account:certificate/prod-*`). La ranura de
            región está vacía por compatibilidad; el almacenamiento de
            certificados y el material de KMS son regionales.
          example: crn:certificate::my-account:certificate/prod-frontend
        name:
          description: >-
            Los nombres de los recursos no deben comenzar con el prefijo literal
            crn: ni ser UUID (en cualquier caso, en las formas canónica,
            compacta, entre corchetes o urn:uuid:).
          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: >
            Estado de delegación CNAME por dominio: una entrada por dominio en
            el certificado. Mientras que la emisión de status=pending_dns espera
            a que cada desafío `verified` se convierta en verdadero; use
            `expected_cname` y `our_dns` para decir qué registros necesitan ser
            agregados en el registrador.
        certificate_pem:
          type: string
          description: Certificado de hoja codificado PEM. Vacía hasta que esté activa.
          example: |
            -----BEGIN CERTIFICATE-----
            MIIDdzCCAl+gAwIBAgIEAaH...
            -----END CERTIFICATE-----
        chain_pem:
          type: string
          description: Cadena intermedia codificada por PEM.
          example: |
            -----BEGIN CERTIFICATE-----
            MIIEFzCCAv+gAwIBAgIEBb2...
            -----END CERTIFICATE-----
        fingerprint:
          type: string
          readOnly: true
          description: >
            Hex SHA-256 del DER de la hoja: la versión material del certificado.
            Cambios en cada rotación; los consumidores lo usan para saber cuándo
            volver a buscar material y para verificar que han buscado la
            generación deseada. Vacío hasta que el certificado tenga una hoja.
          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: >
            Fallas activas, ordenadas por más reciente primero. Vacío cuando
            está sano. Los errores de renovación son advertencias mientras el
            material de certificado válido sigue sirviendo. Códigos:
            CERTIFICATE_ISSUANCE_START_FAILED (no se pudo programar la emisión),
            CERTIFICATE_ISSUANCE_FAILED (falló la solicitud de firma),
            CERTIFICATE_RENEWAL_FAILED (no se completó la renovación; una
            advertencia mientras el material válido todavía está sirviendo, un
            error una vez que ha caducado), CERTIFICATE_REVOCATION_FAILED (la
            revocación no se completó).
        tags:
          $ref: '#/components/schemas/Tags'
    CertificateStatus:
      description: Error si y solo si existe un error activo de gravedad.
      type: string
      enum:
        - pending_dns
        - pending
        - active
        - error
        - expired
        - revoked
      example: active
    CertificateChallenge:
      type: object
      required:
        - faults
      properties:
        domain:
          type: string
          description: >-
            El certificado SAN al que pertenece este desafío (tal como lo
            escribió el cliente).
          example: '*.example.com'
        cname_record_name:
          type: string
          description: >
            LHS completo del registro CNAME que el cliente necesita agregar.
            Para SANs comodín, este es el nombre padre
            (`_acme-challenge.example.com.`), no el SAN literal — los comodines
            se validan en su padre bajo RFC 8555 §8.4.
          example: _acme-challenge.example.com.
        expected_cname:
          type: string
          description: >
            FQDN de destino (RHS del CNAME). Alojado en la zona de validación de
            la plataforma, donde se publica el TXT por pedido durante la
            emisión.
          example: a1b2c3d4e5f6g7h8.acme.basaltic.cloud.
        our_dns:
          type: boolean
          description: >
            True cuando el dominio está alojado en el servicio DNS de la
            plataforma y el CNAME se creó automáticamente. Falso significa que
            el cliente es propietario de la zona y debe agregar el CNAME en su
            registrador.
          example: true
        verified:
          type: boolean
          description: >
            True una vez que el CNAME se ha resuelto a expected_cname; la
            emisión de certificados solo continúa cuando se verifica cada
            desafío.
          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: >
            Una verificación exitosa resuelve los errores de verificación
            mientras conserva el historial. verified registra una observación
            exitosa y permanece verdadera si una renovación posterior observa un
            error de DNS. Una incoherencia de CNAME registra
            CERTIFICATE\_DNS\_VERIFICATION\_FAILED como una advertencia;
            verified no se mueve. El historial interno utiliza el CRN principal
            seguido de /challenge/.<stored-uuid>; no se expone ningún punto
            final separado.
    Fault:
      type: object
      required:
        - code
        - severity
        - message
        - details
        - first_at
        - last_at
        - occurrences
      properties:
        code:
          type: string
          description: >-
            Código legible por máquina estable propiedad de la operación de
            informes.
          example: BACKUP_FAILED
        severity:
          type: string
          enum:
            - error
            - warning
        message:
          type: string
          example: Backup upload failed.
        details:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            Contexto estructurado; las cadenas heredadas se conservan en
            legacy_text.
        first_at:
          type: string
          format: date-time
          description: Primera observación en esta serie de ocurrencias activas.
        last_at:
          type: string
          format: date-time
          description: Última observación en esta serie de ocurrencias activas.
        occurrences:
          type: integer
          minimum: 1
          example: 1
  responses:
    BadRequest:
      description: Parámetros de solicitud no válidos
      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: Se requiere autenticación o el token no es válido
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Authentication required
              request_id: 550e8400-e29b-41d4-a716-446655440000
    Forbidden:
      description: Permisos insuficientes
      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
    UnprocessableEntity:
      description: >
        La solicitud está bien formada, pero no se puede procesar como se envió.
        En las operaciones que aceptan `Idempotency-Key` este es el caso de
        reutilización de clave: la clave fue vista por primera vez con una carga
        de solicitud diferente, por lo que la reproducción del resultado
        almacenado respondería a una pregunta que el llamador no hizo.
      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
    InternalServerError:
      description: Error interno del servidor
      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: >+
        Un token bearer de OAuth 2.0, enviado como `Authorization: Bearer
        <token>`. Esta es la forma recomendada de autenticación.


        Obtén el token intercambiando el par de claves de acceso de una cuenta
        de servicio en `POST /v1/oauth/token` con
        `grant_type=client_credentials`. Es el flujo estándar de credenciales de
        cliente; las bibliotecas compatibles con OAuth pueden obtener y renovar
        el token por ti.


        ```

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


        Los tokens duran una hora por defecto. El mismo par de claves de acceso
        también sirve como credencial AWS SigV4 para el endpoint de objetos
        compatible con S3, que solo acepta ese método de autenticación.


````

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