> ## 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.

# Autenticación

> Cómo autenticar sus solicitudes en la API de Nuvia con una API key

Toda solicitud a la API de Nuvia se autentica con un **token Bearer** enviado en el header
`Authorization`. Esta página explica cómo autenticar llamadas con una API key que usted
**ya posee**. Para generar, listar y revocar claves, consulte la [Guía de API key](/es/guia-api-key).

## Base URL

```
https://api.nuvia.ai
```

Todas las rutas de la API REST usan el prefijo de versión `/v1`. Por ejemplo, listar agentes es
`GET https://api.nuvia.ai/v1/agents`.

<Warning>
  La API key de Nuvia **no** usa un header `X-API-Key` ni un token en el formato `sk_...`.
  La clave se envía como un **token Bearer** en el header `Authorization`:

  ```
  Authorization: Bearer <su-api-key>
  ```

  Enviar la clave en `X-API-Key` resulta en `401`, porque el servidor no lee ese header.
</Warning>

## Dos formas de autenticar

La API acepta dos tipos de identidad **en el mismo header** `Authorization: Bearer`:

* **API key de empresa**: es lo que usa para **integración programática**. La clave está
  vinculada a su empresa y a los scopes definidos en la creación; puede tener validez opcional
  (`expiresAt`). Es el método recomendado para servidores, scripts e integraciones.
* **JWT humano**: el token de sesión emitido por el flujo de inicio de sesión de la aplicación
  (`POST /v1/auth/login`). Representa a un usuario humano, no una integración. No lo necesita
  para consumir la API vía API key. Los endpoints de inicio de sesión pertenecen a la plataforma y
  **no aparecen en la [Referencia de la API](/es/api-reference)**, que cubre la superficie
  consumible por API key.

El servidor identifica automáticamente cuál de los dos fue enviado por el propio contenido del
token. El tipo no se indica en ningún lugar. Para el resto de esta documentación, se asume el
uso de **API key de empresa**.

## Autenticando una solicitud

Incluya el header `Authorization` en cada llamada. El siguiente ejemplo lista los agentes de su
empresa (requiere el scope `agents:read`):

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

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

  const data = await res.json();
  ```

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

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

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

<Note>
  La API key es un **token de acceso completo** al scope concedido. Trátela como un secreto:
  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.
</Note>

## Multi-tenant y el header `X-Company-Id`

El tenant (empresa) de una API key de empresa se resuelve **por el propio token**. No necesita
indicarlo. El header `X-Company-Id` solo es obligatorio para claves globales de uso interno y se
**ignora** para API keys de empresa y para JWT humano. En resumen: **integrando con una API key
de empresa, no envía `X-Company-Id`.**

## Errores de autenticación

Las respuestas de error de autenticación siguen el formato `{ statusCode, message, error }`.

### 401: no autenticado

Se retorna cuando el token está ausente, es inválido, expiró o fue revocado.

```json theme={null}
{
  "statusCode": 401,
  "message": "Autenticación inválida",
  "error": "Unauthorized"
}
```

El campo `message` detalla la causa cuando es posible, por ejemplo `"API key inválida"`,
`"API key expirada"`, `"API key revocada"` o `"API key no encontrada"`.

### 403: sin permiso

Se retorna cuando el token es válido, pero la API key **no tiene el scope** necesario para la
acción, o el endpoint no está disponible para API keys.

```json theme={null}
{
  "statusCode": 403,
  "message": "API key no posee el scope necesario para esta acción",
  "error": "Forbidden"
}
```

Si recibe `403` en una llamada que debería funcionar, verifique si la clave fue creada con el
scope exigido por el endpoint. Los scopes se definen en el momento de la creación de la clave.
Consulte la [Guía de API key](/es/guia-api-key).

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Guía de API key" icon="key" href="/es/guia-api-key">
    Cómo generar, listar y revocar claves, y qué scopes existen.
  </Card>

  <Card title="Inicio rápido" icon="rocket" href="/es/quickstart">
    Haga su primera llamada a la API en pocos minutos.
  </Card>
</CardGroup>