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

# Obtener zona

> Obtenga detalles de una zona DNS específica.

<Info>
  Requiere la acción de IAM **`dns:GetZone`**. Consulte [permisos de DNS](/es/dns/permissions) para obtener la lista completa, lo que cubre cada una y un ejemplo de política.
</Info>


## OpenAPI

````yaml /es/api-reference/specs/dns.yaml get /v1/zones/{zone_id}
openapi: 3.0.3
info:
  title: Basaltic DNS API
  version: 1.0.0
  description: >
    Zonas alojadas autorizadas y sus registros, firmados con DNSSEC. Una zona
    solo se sirve una vez que se verifica su propiedad; asociar una zona con una
    VPC la hace resoluble de forma privada dentro de esa red.
  contact:
    name: Basaltic Support
    email: ping@basaltic.sh
  license:
    name: Proprietary
    url: https://basaltic.sh/terms
servers:
  - url: https://dns.basaltic.sh
    description: Endpoint de API global
security:
  - BearerAuth: []
paths:
  /v1/zones/{zone_id}:
    get:
      tags:
        - DNS
      summary: Obtener zona
      description: Obtenga detalles de una zona DNS específica.
      operationId: getZone
      parameters:
        - $ref: '#/components/parameters/ZoneId'
      responses:
        '200':
          description: Detalles de la zona
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZoneResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - BearerAuth: []
components:
  parameters:
    ZoneId:
      name: zone_id
      in: path
      description: ID de zona DNS
      required: true
      schema:
        type: string
        format: uuid
      example: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    ZoneResponse:
      type: object
      properties:
        zone:
          $ref: '#/components/schemas/Zone'
    Zone:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          example: 550e8400-e29b-41d4-a716-446655440000
        crn:
          type: string
          readOnly: true
          description: Nombre de recurso de nube.
          example: crn:dns::my-account:zone/example.com
        name:
          type: string
          description: >-
            Zona de FQDN. 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: example.com
        description:
          type: string
          description: Descripción de forma libre, editable con PATCH.
          example: Public zone for the marketing site
        nameservers:
          type: array
          items:
            type: string
          description: >
            Servidores de nombres autorizados para la zona: el conjunto NS de
            vértice. Copie esta lista textualmente en la configuración del
            servidor de nombres de su registrador para delegar la zona a la
            plataforma.


            Estos nombres son únicos para ESTA zona: cada uno lleva una etiqueta
            por zona, que es lo que hace que la delegación sea doble como prueba
            de propiedad (ver `ownership`). Dos zonas para el mismo dominio
            reciben nombres diferentes, y la que apunta el registrador es la que
            sirve. Úselos exactamente como están escritos: los nombres de
            servidor de nombres desnudos de Basaltic no verificarán la zona.
          example:
            - 028t5cy4tqkff.triton.dns.basaltic.cloud
            - 028t5cy4tqkff.proteus.dns.basaltic.cloud
        soa:
          $ref: '#/components/schemas/SOA'
        visibility:
          type: string
          enum:
            - public
            - private
          readOnly: true
          description: >
            `public` las zonas responden en los servidores de nombres orientados
            a Internet; `private`

            Las zonas de VPC responden solo dentro de las VPC asociadas a ellas
            (consulte los extremos de asociaciones de vpc).
          example: public
        dnssec:
          $ref: '#/components/schemas/ZoneDNSSEC'
        tags:
          $ref: '#/components/schemas/Tags'
        ownership:
          $ref: '#/components/schemas/ZoneOwnership'
    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
    SOA:
      type: object
      properties:
        primary_ns:
          type: string
          description: SOA `mname` — primer servidor de nombres autorizado para la zona.
          example: 028t5cy4tqkff.triton.dns.basaltic.cloud
        admin_email:
          type: string
          format: email
          readOnly: true
          description: >
            SOA `rname` — el contacto de operaciones DNS de la plataforma.
            Estampado en el lado del servidor; no configurable por el cliente.
          example: hostmaster@basaltic.sh
        refresh:
          type: integer
          example: 10800
        retry:
          type: integer
          example: 3600
        expire:
          type: integer
          example: 604800
        minimum:
          type: integer
          description: Caché de NXDOMAIN TTL.
          example: 3600
    ZoneDNSSEC:
      type: object
      description: >
        Estado de firma DNSSEC. Presente una vez que el firmante ha iniciado la
        zona, que está siempre activada para las zonas creadas a través de esta
        API; ausente en una zona que no está firmada.


        `ds_records` es lo que el cliente pega en el registrador principal para
        completar la cadena de confianza. `rdata` es la forma de archivo de zona
        del mismo registro, para los registradores que toman una cadena.
      required:
        - enabled
      properties:
        enabled:
          type: boolean
          readOnly: true
          example: true
        ksk_key_tag:
          type: integer
          readOnly: true
          description: >-
            Etiqueta de la clave de firma de clave — coincide con los registros
            DS a continuación.
          example: 12345
        zsk_key_tag:
          type: integer
          readOnly: true
          description: Etiqueta de la clave de firma de zona.
          example: 54321
        algorithm:
          type: integer
          readOnly: true
          description: Número de algoritmo DNSSEC. 13 = ECDSA P-256 SHA-256.
          example: 13
        ds_records:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/ZoneDSRecord'
    Tags:
      type: object
      additionalProperties:
        type: string
      example:
        environment: production
        team: backend
    ZoneOwnership:
      type: object
      description: >
        Prueba de propiedad del dominio. Una zona sin ninguna zona existente
        encima de ella en la plataforma no se resuelve hasta que `verified` es
        verdadero — establece los `nameservers` de la zona en tu registrador,
        luego POST /v1/zones/{zone_id}/verify-ownership.


        No hay ningún registro para publicar. Los servidores de nombres de la
        zona llevan una etiqueta única para ella, por lo que delegar el dominio
        en ellos es la prueba en sí misma: solo quien controla el dominio en su
        registrador puede hacerlo, y los nombres no se pueden heredar de una
        zona que solía tener este dominio.


        Usa los `nameservers` propios de la zona y nada más. Los nombres de
        servidores de nombres de Basaltic no prueban nada por sí mismos —
        cualquiera puede apuntar un dominio a ellos — por lo que una delegación
        que los nombre deja la zona sin verificar.


        Los servidores de nombres de otros proveedores pueden estar junto al
        tuyo si alojas el dominio en dos proveedores. Lo que NO funciona es
        delegar a dos zonas basalticas a la vez: mientras un dominio nombra los
        servidores de nombres de otra zona así como el de ésta, ninguno de ellos
        es servido, y el remedio es eliminar los que esta zona no lista. Ese es
        el estado que se espera a mitad de camino al mover un dominio entre
        cuentas.


        Una zona creada debajo de una zona que ya posee hereda la prueba de su
        padre y se verifica en la creación.


        La prueba es un contrato de arrendamiento, no una escritura: se vuelve a
        confirmar periódicamente mientras se sirva la zona, por lo que un
        dominio que caduca o cambia de manos deja de ser servido desde aquí.
        `checked_at` es la última confirmación; `recheck_deadline` aparece solo
        cuando la confirmación falla y es el campo desde el que se genera una
        advertencia.
      properties:
        verified:
          type: boolean
          readOnly: true
          description: >-
            Si la zona ha demostrado la propiedad. Las zonas no verificadas no
            se resuelven.
          example: false
        verified_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: >-
            Cuando se probó por primera vez la propiedad. Ausente mientras no se
            verifica.
          example: '2026-01-15T09:30:00Z'
        checked_at:
          type: string
          format: date-time
          readOnly: true
          description: >
            Cuando la prueba fue confirmada por última vez. `verified_at`
            mantiene el significado "primero demostrado" y no se mueve; esto lo
            hace, en cada pase que pasa. Ausente hasta que la zona se ha
            reconfirmado al menos una vez.
          example: '2026-04-14T09:30:00Z'
        recheck_deadline:
          type: string
          format: date-time
          readOnly: true
          description: >
            Presente SOLO mientras la re-prueba periódica está fallando: el
            instante en que la zona deja de responder a menos que pase de nuevo.
            Ausente significa sano.


            Cada paso vuelve a comprobar una zona de fallo, por lo que para
            llegar a esta fecha se necesita un fallo sostenido, no una mala
            tarde: un problema de resolución transitorio se aclara en el
            siguiente paso. Para borrarlo deliberadamente, apunta la delegación
            del dominio de nuevo a los `nameservers` de esta zona y POST
            /v1/zones/{zone_id}/verify-ownership.


            El propietario de la organización recibe un correo electrónico
            cuando se establece esta fecha y de nuevo si la zona deja de
            resolver. Una zona nunca se quita del aire antes de que ese mensaje
            haya salido, por lo que la fecha aquí es la más temprana que la zona
            puede dejar de responder y nunca la única advertencia.
          example: '2026-04-28T09:30:00Z'
    ZoneDSRecord:
      type: object
      description: Un registro DS para publicar en la zona principal.
      required:
        - key_tag
        - algorithm
        - digest_type
        - digest
        - rdata
      properties:
        key_tag:
          type: integer
          example: 12345
        algorithm:
          type: integer
          example: 13
        digest_type:
          type: integer
          description: 2 = SHA-256.
          example: 2
        digest:
          type: string
          example: B8FA03AA1BB49CC702C32C5C3FE6061BBDD0808371F43A28A8E8BE2738CC9861
        rdata:
          type: string
          description: >-
            Forma completa de archivo de zona — `<key_tag> <algorithm>
            <digest_type> <digest>`.
          example: >-
            12345 13 2
            B8FA03AA1BB49CC702C32C5C3FE6061BBDD0808371F43A28A8E8BE2738CC9861
  responses:
    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
    NotFound:
      description: No se encontró el recurso
      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: 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.