Skip to content

Documentación de la API

Para qué sirve esta pantalla

Esta pantalla es una referencia para desarrolladores, pensada para leerse antes de que una aplicación haga su primera llamada. Está compilada dentro de la consola: no descarga nada, no cambia nada y muestra el mismo contenido a todos los tenants en todas las instalaciones.

La pestaña Referencia de la API explica el modelo (la aplicación nombra un Key ID y la política resuelve el algoritmo), cómo obtiene un token una aplicación, los scopes, los endpoints de los dos planos, los tipos de clave, los estados de error y la URL base del entorno en el que has iniciado sesión. La pestaña SDK y librerías cliente da las coordenadas de Maven y Gradle del SDK de Java, un ejemplo mínimo en Java, una comparación con la CLI de criptografía, las familias de algoritmos y enlaces a las guías del SDK.

Cada ruta, verbo y scope de la pestaña de referencia se tomó del controlador que la sirve, pero las tablas son un resumen, no la especificación. Las especificaciones OpenAPI están enlazadas más abajo.

Qué debe existir antes

Solo una sesión iniciada. La entrada está en el grupo Desarrolladores de la barra lateral para todos los roles (administrador de plataforma, administrador de tenant y gestor de claves) y ningún permiso la condiciona. Como nada en la pantalla llama a la plataforma, tampoco aplica ningún permiso del servidor.

En una instalación operada por el cliente, dos cosas difieren de un entorno alojado por ANKA:

  • La tabla Entornos tiene una sola fila, construida a partir de la dirección en la que has iniciado sesión: su esquema y su nombre de host, marcada como "Entorno actual". Si tu consola se sirve en un puerto, el puerto no se incluye. Las filas con nombre (Desarrollo, Preproducción, Demo, Producción) aparecen solo cuando la consola se ejecuta en uno de los hosts propios de ANKA.
  • Los botones que abren la documentación completa de la API y las guías del SDK abren los sitios publicados de ANKA en una pestaña nueva. Son enlaces simples: la consola no envía nada a esos sitios, ni tu token ni la página de la que vienes. Si tu instalación no puede alcanzarlos, la pestaña nueva falla y esta pantalla no se ve afectada. La configuración que apaga esta ayuda dentro del producto no elimina esos enlaces.

Decisiones que tomas aquí

Ninguna que cambie la plataforma. La pantalla ofrece dos comodidades:

  • Elegir una pestaña. La elección se conserva en la dirección como ?tab=sdk, así que un enlace puede abrir la pestaña del SDK directamente. Cualquier otro valor abre la pestaña de referencia de la API.
  • Copiar un fragmento. Los bloques de Maven, Gradle y Java tienen un botón de copia que escribe el bloque en tu portapapeles. Cuando el navegador rechaza el acceso al portapapeles, el bloque lo indica y lo seleccionas y copias a mano.

Dos cosas que afirma la referencia merecen leerse con exactitud:

  • A qué plano pertenece una operación. Cifrar, descifrar, firmar, verificar, recifrar y descubrir claves están en Core API, el plano de datos al que una aplicación llama con su propio token. Crear, rotar y revocar una clave son operaciones del plano de control en Admin API, con el tenant en la ruta. Las rutas propias de Core API para crear, rotar y revocar son internas y rechazan un token de aplicación.
  • Cómo se obtiene un token. El endpoint de tokens del servicio de autenticación recibe un cuerpo codificado como formulario (grant_type=client_credentials, client_id, client_secret); es la única codificación que acepta el endpoint. client_id es el identificador del actor criptográfico y client_secret una de sus credenciales de secreto compartido; un actor con un par de claves registrado presenta una aserción firmada en su lugar. Los scopes que lleva el token provienen de los roles del actor y de sus concesiones de capacidad activas, nunca de nada de esta pantalla.

Cómo se relaciona con otras pantallas

El identificador y la credencial que presenta una aplicación, y los roles que dan scopes a su token, se emiten en el actor:

Qué claves puede usar la aplicación lo deciden las concesiones de capacidad. Las claves en sí se crean, rotan y revocan desde el Inventario de Claves, que utiliza las mismas rutas de Admin API que enumera esta pantalla:

Dónde leer más

Estas páginas están en inglés: