Autenticación
Todas las peticiones salvo la comprobación de salud llevan una clave. Las claves identifican a una organización y no a una persona, y llevan el plan y la cuota de esa organización.
La cabecera
curl -sS "https://api.skautik.com/v1/api/properties?city=Berlin" \
-H "X-API-Key: sk_live_9f21c4a70b8e…"
# Authorization: Bearer también vale, para clientes a los que les resulte más cómodo.
curl -sS "https://api.skautik.com/v1/api/properties?city=Berlin" \
-H "Authorization: Bearer sk_live_9f21c4a70b8e…"Cualquiera de las dos cabeceras sirve. Si están ambas, gana X-API-Key. Una cabecera ausente o
mal formada devuelve 401 con el código authentication_required, y la
respuesta nunca dice si la clave no existe o ha sido revocada:
distinguirlo permitiría a alguien tantear en busca de claves válidas.
Tipos de clave
| Prefijo | Tipo | Qué hace |
|---|---|---|
sk_live_ | Producción | Lee y escribe inventario real. Con límite de uso contra la cuota de tu plan. |
sk_test_ | Pruebas | Lee un conjunto de datos fijo y pequeño y acepta escrituras que se descartan. Gratuita, y con un límite de uso generoso, para que las pruebas de integración no gasten cuota. |
El prefijo forma parte de la clave, así que una cadena filtrada se reconoce como una credencial de Skautik en un registro o en un escaneo de repositorio. Es deliberado: los escáneres de secretos pueden detectarla y avisarte antes de que la encuentre otro.
Permisos
Los permisos son por recurso y no un par general de lectura y escritura. Una clave se crea con el conjunto que necesita, y la API rechaza cualquier llamada cuya clave no tenga el permiso que exige esa ruta.
Concede el conjunto más estrecho que haga el trabajo. Una clave emitida para análisis de mercado no puede después leer los datos de contacto de nadie ni retirar un anuncio, por mal que se filtre.
| Permiso | Permite |
|---|---|
properties:read | Leer inmuebles y sus imágenes. |
properties:write | Crear, actualizar y retirar inmuebles. |
markets:read | Leer estadísticas e inteligencia de mercado. |
imports:write | Enviar y gestionar importaciones masivas. |
exports:create | Solicitar exportaciones y descargar los resultados. |
images:write | Generar y adjuntar imágenes renderizadas. |
webhooks:manage | Crear, actualizar y eliminar endpoints de webhook. |
inquiries:read | Leer las consultas enviadas sobre tus inmuebles. |
Rotación
Las claves no caducan de forma programada, porque una caducidad forzada tiende a producir una caída en lugar de más seguridad. Rota a propósito. Una organización puede tener varias claves a la vez precisamente para que esto no requiera ningún corte:
- Crea una segunda clave junto a la que está en uso.
- Despliégala en tus servicios y confirma que el tráfico se ha movido a ella.
- Comprueba en la página de claves que la antigua se ha quedado callada, en lugar de darlo por hecho.
- Revoca la clave antigua.
La revocación surte efecto de inmediato, sin periodo de gracia.
Mantener una clave en secreto
- Solo en el servidor. Una clave enviada a un navegador o a un binario móvil es una clave publicada, por mucho que se ofusque. Haz de proxy con tu propio backend.
- Guarda las claves en variables de entorno o en un gestor de secretos, nunca en un repositorio, en un artefacto de compilación ni en un paquete de cliente.
- Usa una clave distinta por entorno y por servicio, para que revocar una no se lleve todo por delante.
- La clave completa se muestra una vez al crearla y solo se guarda como hash. No podemos recuperártela; crea una nueva.
Si una clave se filtra
Revócala primero e investiga después: una clave revocada te cuesta un despliegue, una filtrada y activa te cuesta tu cuota y tus datos.
Después escribe a security@skautik.com para que podamos comprobar si hubo un uso que no hiciste tú. Además vigilamos los repositorios públicos buscando nuestros prefijos de clave y revocaremos una clave que encontremos expuesta, avisándote cuando lo hagamos.
Comprobar una clave
GET /v1/api/me informa de la organización, el plan y la cuota restante detrás de una
clave. Es la llamada adecuada para una comprobación de arranque o una sonda de salud, porque
demuestra que la clave funciona sin paginar ningún recurso.
Gestiona las claves desde la página de claves de API.