> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cobrix.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticación

> Llaves Bearer, scopes y aislamiento por empresa

## Bearer API key

Todas las APIs públicas usan una llave creada desde el panel de la empresa:

```http theme={null}
Authorization: Bearer cbx_live_REEMPLAZAR
```

La llave está vinculada a una empresa, un partner, un `source` y un conjunto de permisos. No envíes `companyId` en headers adicionales; la API de integraciones lo incluye en la ruta y comprueba que coincida con la llave. La API pública de documentos de cobro obtiene la empresa directamente de la credencial.

## Crear una llave

<Steps>
  <Step title="Abre Integraciones">
    En el dashboard de la empresa entra en **Configuración → Integraciones → Llaves API**.
  </Step>

  <Step title="Crea el partner">
    Selecciona **Crear partner y primera llave** e indica un `source` estable, por ejemplo `erp_acme`.
  </Step>

  <Step title="Asigna solo los permisos necesarios">
    Activa los scopes correspondientes a las operaciones que ejecutará el sistema externo.
  </Step>

  <Step title="Copia el secreto">
    La llave completa se muestra una sola vez. Guárdala en un gestor de secretos.
  </Step>
</Steps>

## Scopes

| Scope                                 | Permite                                                    |
| ------------------------------------- | ---------------------------------------------------------- |
| `customers:read`                      | Listar clientes vinculados a integraciones.                |
| `customers:write`                     | Crear o actualizar clientes externos.                      |
| `collection_documents:read`           | Listar y consultar documentos de cobro.                    |
| `collection_documents:write`          | Crear, actualizar o anular documentos.                     |
| `collection_document_checkouts:write` | Generar links de cobro.                                    |
| `verified_payments:write`             | Reportar pagos verificados al ledger.                      |
| `payments:read`                       | Listar y consultar pagos externos.                         |
| `certified_rates:write`               | Completar pagos que requieren tasa certificada.            |
| `public_invoices:read`                | Listar y consultar documentos de cobro públicos.           |
| `public_invoices:write`               | Crear, actualizar o eliminar documentos de cobro públicos. |

## Diferencias de seguridad

* `/integrations/v1` exige además firma HMAC por request. Consulta [Firma de solicitudes](/guides/request-signing).
* `/v1/invoices` usa únicamente el Bearer y `x-idempotency` al crear; no acepta firmas adicionales como requisito.

## Respuestas de autorización

| HTTP  | Significado                                                     |
| ----- | --------------------------------------------------------------- |
| `401` | Llave ausente, inválida, vencida o revocada.                    |
| `403` | Empresa incorrecta, partner deshabilitado o scope insuficiente. |

<Warning>
  Usa la llave únicamente de servidor a servidor. No la expongas en aplicaciones móviles, JavaScript del navegador, capturas, tickets o logs.
</Warning>