API Claves

Las claves API se utilizan para autenticar solicitudes en Capgo API. Cada clave puede tener diferentes permisos (modos) para controlar los niveles de acceso. Las claves son específicas de la organización y deben administrarse con cuidado, ya que otorgan acceso a sus recursos Capgo.

Modos clave

leer: solo puede leer datos, no se permiten modificaciones
cargar: puede leer, modificar y cargar nuevos paquetes
escribir: puede leer, modificar datos y cargar paquetes
todos: acceso completo a todas las operaciones

Los modos clave siguen un esquema escalonado/gradual. Si tiene una clave de carga y luego crea una clave de escritura, la clave de escritura podrá hacer todo lo que la clave de carga podría hacer. Eche un vistazo al siguiente diagrama para comprender mejor cómo funcionan las claves API.

Un diagrama que explica cómo funciona la clave API

Subclaves con derechos limitados

Puede crear subclaves con acceso limitado a aplicaciones u organizaciones específicas. Esto es útil para restringir el acceso a ciertos recursos y al mismo tiempo permitir operaciones en otros. Utilice los parámetros limited_to_apps y limited_to_orgs al crear una clave para definir estas restricciones.

Claves cifradas

Puede crear claves API cifradas (con hash) para mejorar la seguridad. Al crear una clave cifrada:

La clave se codifica mediante SHA-256 antes de almacenarse en la base de datos.
La clave simple se devuelve solo una vez en la respuesta de creación; guárdela inmediatamente
La clave no se puede recuperar ni ver nuevamente después de su creación.
Si pierde una clave cifrada, debe crear una nueva

Utilice el parámetro hashed: true al crear una clave para habilitar el cifrado. Este es el enfoque recomendado para entornos de producción.

Caducidad de la clave

Las API claves pueden tener una fecha de vencimiento para limitar la ventana de exposición si una clave se ve comprometida. Cuando se establece una fecha de vencimiento:

La clave deja de funcionar después de la fecha y hora especificadas.
Las solicitudes que utilicen claves caducadas se rechazarán con un error
Las claves caducadas se limpian automáticamente después de 30 días

Las organizaciones pueden hacer cumplir políticas de vencimiento:

Requerir vencimiento: todas las claves API deben tener una fecha de vencimiento
Periodo de vencimiento máximo: limita en qué momento en el futuro se puede establecer una fecha de vencimiento

Mejores prácticas de seguridad

Principio de privilegio mínimo: utilice siempre el modo más restrictivo que aún permita que su integración funcione
Utilice claves cifradas: cree claves hash para producción para protegerse contra violaciones de bases de datos
Establecer fechas de vencimiento: use fechas de vencimiento para limitar la vida útil de sus claves
Rotación regular: gire sus llaves API periódicamente
Almacenamiento seguro: almacene API claves de forma segura y nunca las envíe al control de versiones.
Monitoreo: Supervise el uso de claves API y revoque cualquier clave comprometida inmediatamente
Subclaves limitadas: utilice subclaves con derechos limitados para integraciones específicas para minimizar el riesgo.

Puntos finales

OBTENER

https://api.capgo.app/apikey/

Recupere todas las API claves asociadas con su cuenta.

Tipo de respuesta

interface ApiKey {
  created_at: string | null
  id: number
  key: string | null  // null for encrypted keys
  mode: 'read' | 'write' | 'upload' | 'all'
  name: string
  updated_at: string | null
  user_id: string
  limited_to_apps?: string[]
  limited_to_orgs?: string[]
  expires_at?: string | null  // ISO 8601 date, null means never expires
}
```> **Note**: For encrypted keys, the `key` field will be `null` in GET responses since the plain key is only shown once during creation.

#### Solicitud de ejemplo

```bash
curl -H "authorization: your-api-key" https://api.capgo.app/apikey/

Ejemplo de respuesta

{
  "data": [
    {
      "id": 1,
      "key": "ak_123...",
      "mode": "read",
      "name": "CI/CD Read Key",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "user_id": "user_123"
    },
    {
      "id": 2,
      "key": "ak_456...",
      "mode": "upload",
      "name": "Deploy Bot",
      "created_at": "2024-01-02T00:00:00Z",
      "updated_at": "2024-01-02T00:00:00Z",
      "user_id": "user_123",
      "limited_to_apps": ["com.demo.app"]
    }
  ]
}

PUBLICAR

https://api.capgo.app/apikey/

Cree una nueva clave API para una organización específica.

Cuerpo de solicitud

interface ApiKeyCreate {
  name: string
  mode: 'read' | 'write' | 'upload' | 'all'
  limited_to_apps?: string[]
  limited_to_orgs?: string[]
  hashed?: boolean       // Create an encrypted key (recommended for production)
  expires_at?: string    // ISO 8601 date for key expiration
}

Solicitud de ejemplo (clave estándar)

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Limited Read Key",
    "mode": "read",
    "limited_to_apps": ["com.demo.app"]
  }' \
  https://api.capgo.app/apikey/

Solicitud de ejemplo (clave cifrada con caducidad)

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Secure CI Key",
    "mode": "upload",
    "hashed": true,
    "expires_at": "2025-06-01T00:00:00Z"
  }' \
  https://api.capgo.app/apikey/

Ejemplo de respuesta (clave estándar)

{
  "apikey": {
    "id": 3,
    "key": "ak_789...",
    "mode": "read",
    "name": "Limited Read Key",
    "created_at": "2024-02-12T00:00:00Z",
    "user_id": "user_123",
    "limited_to_apps": ["com.demo.app"]
  }
}

Ejemplo de respuesta (clave cifrada)

{
  "apikey": {
    "id": 4,
    "key": "ak_abc123...",
    "mode": "upload",
    "name": "Secure CI Key",
    "created_at": "2024-02-12T00:00:00Z",
    "user_id": "user_123",
    "expires_at": "2025-06-01T00:00:00Z"
  }
}

Importante: Para claves cifradas, el valor key en esta respuesta es la única vez que verá la clave simple. Guárdelo inmediatamente en un lugar seguro. Las solicitudes GET posteriores devolverán null para el campo key.

BORRAR

https://api.capgo.app/apikey/:id/

Elimine una clave API existente. Utilice esto para revocar el acceso inmediatamente.

Parámetros

id: el ID de la clave API que se va a eliminar (identificador numérico, no la cadena de clave en sí)

Solicitud de ejemplo

curl -X DELETE -H "authorization: your-api-key" https://api.capgo.app/apikey/1/

Respuesta exitosa

{
  "success": true
}

Casos de uso comunes

Integración de CI/CD: cree claves de solo lectura para canalizaciones de CI para verificar el estado de implementación
Automatización de implementación: use claves de modo de carga para scripts de implementación automatizados
Herramientas de monitoreo: use teclas de modo de lectura para integraciones de monitoreo externo
Acceso de administrador: use todas las teclas de modo con moderación para herramientas administrativas
Acceso limitado: cree subclaves con derechos limitados para aplicaciones u organizaciones específicas para integraciones de terceros.

Manejo de errores

Escenarios de error comunes y sus respuestas:

// Invalid mode
{
  "error": "Invalid mode specified. Must be one of: read, write, upload, all",
  "status": "KO"
}

// Key not found
{
  "error": "API key not found",
  "status": "KO"
}

// Permission denied
{
  "error": "Insufficient permissions to manage API keys",
  "status": "KO"
}

// Expired API key used for authentication
{
  "error": "API key has expired",
  "status": "KO"
}

// Invalid expiration date (in the past)
{
  "error": "Expiration date must be in the future",
  "status": "KO"
}

// Organization requires expiration
{
  "error": "Organization policy requires an expiration date for API keys",
  "status": "KO"
}

// Expiration exceeds organization limit
{
  "error": "Expiration date exceeds organization maximum of 90 days",
  "status": "KO"
}