Claves API

Las API se utilizan para autenticar solicitudes a la Capgo API. Las claves son específicas de la organización y se pueden asignar roles de acceso de RBAC para un control de acceso fino-granular. Cada clave también puede tener una fecha de caducidad opcional y puede crearse como una clave “segura” (hashada) donde el valor en texto plano solo se muestra una vez.

Usando una API clave

Pasa tu API clave en el x-api-key cabecera de cada solicitud:

curl -H "x-api-key: YOUR_API_KEY" https://api.capgo.app/...

La authorization también se acepta la cabecera, pero está principalmente destinada a tokens JWT. Cuando el valor es una clave formateada como UUID API funciona, pero x-api-key permisos de RBAC

Sección titulada “permisos de RBAC”

API keys use the same role-based access control (RBAC) system as user accounts. When creating or managing keys through the web app, you assign roles at two levels:

• — Define las permisos básicos de la clave en toda la organización (por ejemplo, roles de la aplicación org_admin, org_member).
• permisos de la aplicación — Permiso opcional por aplicación (por ejemplo, app_admin, app_developer, app_uploader, app_reader).

Si una clave API tiene vinculaciones de rol explícitas, solo se evalúan esas vinculaciones para comprobar permisos. Los permisos personales del propietario de la clave no se heredan por la clave.

Nota

Las claves sin vinculaciones de rol recaen en un sistema basado en modos deprecado (read, upload, write, all). Utilice en su lugar los roles RBAC.

Permiso de creación de organización

Crear organizaciones con una clave API ahora utiliza un permiso global explícito: org.create.

This permission es separado de las vinculaciones de roles de org/app normales porque una nueva organización no existe aún cuando se llama. Para crear organizaciones con una clave __CAPGO_KEEP_0__: POST /organization/ La clave API debe incluir

• The API key must include org.create La misma clave __CAPGO_KEEP_0__ también debe tener una organización-scoped actual global_permissions.
• The same API key must also have a current organization-scoped org_admin vinculación. org_super_admin Las nuevas claves __CAPGO_KEEP_0__ no reciben
• New API keys do not receive org.create Permitir la creación de organizaciones cuando se crea o edita una clave de RBAC __CAPGO_KEEP_0__ en la consola. when creating or editing an RBAC API key in the dashboard.
• API org.create Así, las integraciones existentes pueden seguir creando organizaciones.

Cuando una clave API crea una organización, Capgo asigna automáticamente esa misma clave API como org_super_admin en la organización recién creada. Esto permite a la integración gestionar la organización que acaba de crear sin necesitar una vinculación de rol manual separada.

Si crea una clave API a través de API, incluya global_permissions junto con la vinculación de administrador de la organización:

{
  "name": "Provisioning key",
  "hashed": true,
  "bindings": [
    {
      "role_name": "org_admin",
      "scope_type": "org",
      "org_id": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "global_permissions": ["org.create"]
}

org.create aplica solo para crear organizaciones. La eliminación de una organización sigue requiriendo permiso de eliminación en la organización objetivo, típicamente a través de org_super_admin.

Claves Seguras (Hasheadas)

Al crear una clave segura, el servidor genera el material de la clave y devuelve el valor en texto plano una vez. Solo se almacena una huella. Esto significa:

• La clave en texto plano no se puede recuperar después de la creación.
• La regeneración produce una nueva clave de texto plano (mostrada una vez) y actualiza la hash almacenada.
• Se recomiendan claves hashadas para uso en producción.

Algunas organizaciones imponen claves hashadas mediante la enforce_hashed_api_keys política de la organización.

Vencimiento

Las claves pueden tener una fecha de vencimiento opcional. Las claves vencidas se rechazan en el nivel de verificación de permisos.

Las políticas de organización pueden imponer:

• Expiración obligatoria (require_apikey_expiration) — Todas las nuevas claves deben tener una fecha de expiración.
• TTL máximo (max_apikey_expiration_days — El vencimiento no puede ser más allá de N días de ahora.

Prácticas de Seguridad

1. Principio de Menor Privilegio: Asigne el rol más restrictivo que aún permita que su integración funcione
2. Rotación Regular: Regenere sus API periódicamente utilizando la característica de regeneración
3. Almacenamiento Seguro: Almacene sus API de manera segura y nunca los comita a control de versiones
4. Uso de Claves Hasheadas: Cree claves seguras (hasheadas) para integraciones de producción
5. Establecer Expiración: Siempre establezca una fecha de vencimiento en las claves utilizadas para el acceso temporal o CI/CD
6. Restricciones de alcance: Restringe las claves a aplicaciones específicas con el rol mínimo requerido

Uso común

1. Integración CI/CD: Crea claves con alcance en aplicaciones específicas con el app_uploader o app_developer rol, y establezca una fecha de vencimiento
2. Automatización de despliegue: Utilice claves con el app_developer rol para scripts de automatización de despliegue
3. Herramientas de Monitoreo: Crea claves con el app_reader rol para integraciones de monitoreo externo
4. Acceso Administrativo: Utiliza claves con el org_admin rol con moderación para herramientas administrativas
5. Integraciones de Terceros: Crea claves restringidas a aplicaciones específicas con el rol mínimo requerido
6. Provisión de Organización: Utiliza un org_admin o org_super_admin clave de RBAC con org.create Sólo para automatización confiable que necesita crear organizaciones

Sigue adelante desde las API Claves

Si estás utilizando las API Claves para planificar flujos de autenticación y cuentas, conecta con @capgo/capacitor-login-social para los detalles de implementación en @capgo/capacitor-login-social, @capgo/capacitor-clave-llave para los detalles de implementación en @capgo/capacitor-clave-llave, @capgo/capacitor-biometría-nativa para los detalles de implementación en @capgo/capacitor-biometría-nativa, Autenticación en dos factores para el detalle de implementación en Autenticación en dos factores, y SSO (Empresas) para el detalle de implementación en SSO (Empresas).