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

# Guía de API key

> Cómo generar, listar y revocar API keys de Nuvia, y qué scopes existen

Una API key es el token que su integración usa para autenticarse en la API de Nuvia. Para saber
**cómo enviar** la clave en las solicitudes, consulte [Autenticación](/es/autenticacao). Esta
página cubre el **ciclo de vida** de la clave: crear, listar, revocar y elegir scopes.

<Note>
  Las API keys se crean y gestionan desde un **usuario humano** autenticado con el token de inicio
  de sesión de la aplicación (JWT humano, ver [Autenticación](/es/autenticacao)). Una API key
  **no** gestiona otras API keys: los endpoints de `/v1/api-keys` no aceptan autenticación por
  API key.
</Note>

## Crear una API key

Envíe un `POST /v1/api-keys` autenticado como usuario. El cuerpo acepta:

| Campo       | Tipo              | Obligatorio | Descripción                                                              |
| ----------- | ----------------- | ----------- | ------------------------------------------------------------------------ |
| `name`      | string            | Sí          | Nombre de identificación de la clave (hasta 100 caracteres).             |
| `scopes`    | string\[]         | Sí          | Lista de scopes en formato `<subject>:<action>` (ver el catálogo abajo). |
| `expiresAt` | string (ISO 8601) | No          | Fecha futura de expiración. Si se omite, la clave no expira por tiempo.  |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.nuvia.ai/v1/api-keys \
    -H "Authorization: Bearer $NUVIA_USER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Integración de producción",
      "scopes": ["contacts:read", "messages:create"],
      "expiresAt": "2027-01-01T00:00:00.000Z"
    }'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://api.nuvia.ai/v1/api-keys", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NUVIA_USER_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Integración de producción",
      scopes: ["contacts:read", "messages:create"],
      expiresAt: "2027-01-01T00:00:00.000Z",
    }),
  });

  const { accessToken, apiKey } = await res.json();
  ```

  ```python Python theme={null}
  import os
  import requests

  res = requests.post(
      "https://api.nuvia.ai/v1/api-keys",
      headers={"Authorization": f"Bearer {os.environ['NUVIA_USER_TOKEN']}"},
      json={
          "name": "Integración de producción",
          "scopes": ["contacts:read", "messages:create"],
          "expiresAt": "2027-01-01T00:00:00.000Z",
      },
  )

  body = res.json()
  access_token = body["accessToken"]
  ```
</CodeGroup>

La respuesta (`201`) trae el token en `accessToken` y los metadatos de la clave en `apiKey`:

```json theme={null}
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "apiKey": {
    "name": "Integración de producción",
    "scopes": ["contacts:read", "messages:create"],
    "status": "ACTIVE",
    "keyPreview": "...a1b2",
    "expiresAt": "2027-01-01T00:00:00.000Z"
  }
}
```

<Warning>
  El valor completo del token aparece **una sola vez**, en el campo `accessToken` de la respuesta
  de creación. Nuvia **no almacena el token** y no hay forma de recuperarlo después: solo quedan
  guardados los metadatos y una vista previa (`keyPreview`, los últimos 4 caracteres). Copie y
  guarde el token de forma segura en ese momento. Si pierde el token, revoque la clave y cree una
  nueva.
</Warning>

## Listar API keys

`GET /v1/api-keys` devuelve las claves de su empresa (con paginación `{ data, meta }`). La
respuesta solo trae metadatos, nunca el token.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.nuvia.ai/v1/api-keys \
    -H "Authorization: Bearer $NUVIA_USER_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://api.nuvia.ai/v1/api-keys", {
    headers: { Authorization: `Bearer ${process.env.NUVIA_USER_TOKEN}` },
  });

  const { data, meta } = await res.json();
  ```

  ```python Python theme={null}
  import os
  import requests

  res = requests.get(
      "https://api.nuvia.ai/v1/api-keys",
      headers={"Authorization": f"Bearer {os.environ['NUVIA_USER_TOKEN']}"},
  )

  data = res.json()["data"]
  ```
</CodeGroup>

## Revocar una API key

`DELETE /v1/api-keys/:id` revoca la clave de inmediato y responde `204 No Content`. La operación
es **idempotente**: revocar una clave ya revocada no genera error. La clave debe pertenecer a su
empresa.

```bash cURL theme={null}
curl -X DELETE https://api.nuvia.ai/v1/api-keys/652f1a9c8b3e4d0012a7f4c1 \
  -H "Authorization: Bearer $NUVIA_USER_TOKEN"
```

Una vez revocada, la clave deja de autenticar en cualquier solicitud.

## Scopes disponibles

Los scopes siguen el formato `<subject>:<action>`. Al crear una clave, conceda **solo** los scopes
que la integración necesita. La siguiente tabla lista el catálogo disponible en el panel, agrupado
por subject.

| Subject                | Acciones                                | Qué habilita el subject                                                                                              |
| ---------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `agents`               | `read` · `create` · `update` · `delete` | Agentes de IA: listar, crear, clonar y actualizar.                                                                   |
| `contacts`             | `read` · `create` · `update` · `delete` | Contactos: gestionar contactos y sus vínculos.                                                                       |
| `conversations`        | `read` · `create` · `update`            | Conversaciones: listar y actualizar (asignar agente, propietario, prioridad, equipo).                                |
| `campaigns`            | `read` · `create` · `update` · `delete` | Campañas: gestionar campañas, activación y analytics.                                                                |
| `campaign-enrollments` | `read` · `create`                       | Inscripciones a campaña: inscribir contactos (individual, por lista, embudo o `contact_ids`) y listar inscripciones. |
| `triggers`             | `create`                                | Disparadores de campaña: activar la inscripción por evento.                                                          |
| `messages`             | `read` · `create`                       | Mensajes: leer mensajes y adjuntos de una conversación y enviar (texto y plantilla).                                 |
| `inboxes`              | `read` · `create` · `update`            | Inboxes: gestionar inboxes.                                                                                          |
| `tables`               | `read` · `create` · `update` · `delete` | Tablas y listas: gestionar tablas, columnas y exportaciones.                                                         |
| `knowledge-base`       | `read` · `create` · `update`            | Base de conocimiento: gestionar elementos de conocimiento.                                                           |
| `webhooks`             | `read` · `create` · `update` · `delete` | Webhooks: gestionar configuraciones de webhook.                                                                      |
| `search-v2`            | `read` · `create`                       | Búsqueda de empresas y prospectos (Brasil y global) y autocompletado.                                                |
| `linkedin-search`      | `read` · `create`                       | Búsqueda en LinkedIn: perfiles, empresas y parámetros.                                                               |
| `enrichment`           | `read` · `create`                       | Enriquecimiento de contactos y consulta de elegibilidad/créditos.                                                    |

<Note>
  El panel solo ofrece los scopes de este catálogo. Si un endpoint devuelve `403` incluso con una
  clave válida, confirme que la clave se creó con el scope que ese endpoint exige.
</Note>

<Warning>
  **Excepción conocida:** `DELETE /v1/inboxes/{id}` exige el scope `inboxes:delete`, que **no
  está** en el catálogo del panel: una clave creada allí recibe `403` en este endpoint. Para
  concederlo, cree la clave por `POST /v1/api-keys` incluyendo `"inboxes:delete"` en `scopes`: la
  creación valida solo el formato `<subject>:<action>`, no el catálogo. Todos los demás scopes
  exigidos por los endpoints de la Referencia están en el catálogo.
</Warning>

## Modelo de propiedad

Una API key pertenece a la **empresa** (el tenant), no al usuario que la creó. El usuario creador
queda registrado solo para auditoría. Una consecuencia importante:

<Warning>
  La clave **no se revoca automáticamente** cuando el usuario que la creó es desactivado o
  eliminado de la empresa. Sigue siendo válida. Para terminar el acceso de una clave,
  **revóquela explícitamente** con `DELETE /v1/api-keys/:id`.
</Warning>

## Buenas prácticas de seguridad

<Steps>
  <Step title="Trate la clave como un secreto">
    La API key es un Bearer token que da acceso a todo lo que sus scopes permiten. Guárdela en una
    variable de entorno o en un gestor de secretos, nunca en el código fuente ni en el control de
    versiones.
  </Step>

  <Step title="Aplique el mínimo privilegio">
    Conceda solo los scopes necesarios para la integración. Evite crear claves con el catálogo
    completo "por precaución".
  </Step>

  <Step title="Defina una expiración">
    Use `expiresAt` para claves de vida corta o temporales, reduciendo la ventana de exposición si
    la clave se filtra.
  </Step>

  <Step title="Revoque lo que no use">
    Revoque claves antiguas, de pruebas o sin uso. Como la clave sobrevive a la salida del usuario
    creador, la limpieza es responsabilidad de la empresa.
  </Step>
</Steps>

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Autenticación" icon="lock" href="/es/autenticacao">
    Cómo enviar la API key en las solicitudes y entender los errores de autenticación.
  </Card>

  <Card title="Límites de uso" icon="gauge-high" href="/es/guias/rate-limits">
    Cómo la API gestiona hoy los límites de solicitud.
  </Card>
</CardGroup>