<!-- source_url: https://docs.mynexusapi.com/v1/guias/autenticacion | last_updated: 2026-11-19 -->

# Autenticación

Cada petición a la API lleva tu API Key en la cabecera `X-Api-Key`. En producción, además, debe salir de una IP registrada para tu integración.

Puedes llamar a nuestra API sin iniciar sesión ni renovar tokens. Cada petición
se autentica por sí sola con dos comprobaciones: que traiga una API Key válida y,
en producción, que llegue desde una IP pública que registraste para tu
integración. En el sandbox se acepta cualquier IP. Cada ambiente usa su propia
API Key.

En esta página verás cómo enviar la API Key, cómo obtenerla, guardarla y
rotarla, cómo averiguar y registrar tu IP de salida y qué significa cada error
de autenticación. Al terminar tendrás una llamada a `GET /v1/contexto` que
responde 200.

## Conceptos

- **API Key.** Es la credencial de tu integración. Una sola API Key cubre todos
  los [contribuyentes](/v1/guias/glosario#contribuyente) y tipos de comprobante
  habilitados para tu integración, y dentro de la API no existen usuarios ni
  permisos por persona. Más detalle en [API Key](/v1/guias/glosario#api-key).
- **IP permitida.** Es la dirección IP pública desde la que tu servidor sale a
  Internet. En producción, la API solo acepta tu API Key si la petición llega
  desde una IP registrada. Las IP se registran por integración, así que valen
  para todas tus API Key. El sandbox no exige IP registrada.
- **Ambiente.** Pruebas y producción tienen URL distintas y cada uno tiene sus
  propias API Key. Las diferencias están en
  [Ambientes y contribuyentes](/v1/guias/ambientes).

Si la API Key falta, no existe, está revocada o venció, la respuesta es un 401 con el `codEstado` 3009 (`credenciales_invalidas`). En producción, si la API Key es válida pero la IP no está permitida, la respuesta es un 403 con el `codEstado` 3010 (`ip_no_autorizada`). Revisa la causa que corresponda en [Errores de autenticación](#errores-de-autenticacion).

## Antes de empezar

- [ ] Una API Key de pruebas. Si todavía no tienes una,
      [crea un sandbox](/v1/guias/sandbox); la API Key la obtienes después, en **Pruebas** del Portal del Cliente.
- [ ] La IP pública de salida de tu servidor, registrada en el Portal del
      Cliente como se explica en [Registra tu IP](#registra-tu-ip). Solo se
      exige en producción; el sandbox acepta cualquier IP.
- [ ] La API Key guardada en la variable de entorno `ECUAFACT_API_KEY`, como se
      explica en [Guarda la API Key](#guarda-la-api-key).

## Envía la API Key

Incluye la cabecera `X-Api-Key` en **cada** petición a `/v1`.

| Cabecera | Obligatoria | Valor |
|---|---|---|
| `X-Api-Key` | Sí | Tu API Key completa, tal como la copiaste del portal al crearla. Tiene dos partes separadas por un punto (`prefijo.secreto`). |

El ejemplo consulta `GET /v1/contexto`, que es la llamada más simple para
comprobar que tu API Key y tu IP funcionan.

> [!IMPORTANT]
> Ambiente de pruebas: sin validez fiscal.

```bash
curl -s "https://api-sandbox.mynexusapi.com/v1/contexto" \
  -H "X-Api-Key: $ECUAFACT_API_KEY"
```

```csharp
using System.Net.Http;

string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!;
using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") };
http.DefaultRequestHeaders.Add("X-Api-Key", apiKey);

using HttpResponseMessage respuesta = await http.GetAsync("/v1/contexto");
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
```

```python
import os
import requests

r = requests.get(
    "https://api-sandbox.mynexusapi.com/v1/contexto",
    headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]},
    timeout=30,
)
print(r.status_code, r.text)
```

```javascript
// Node.js 18 o superior. Guarda como ejemplo.mjs y ejecuta: node ejemplo.mjs
const res = await fetch('https://api-sandbox.mynexusapi.com/v1/contexto', {
  headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY }
});
console.log(res.status, await res.text());
```

```php
<?php
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/contexto');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')],
]);
$cuerpo = curl_exec($ch);
$estado = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $estado . ' ' . $cuerpo . PHP_EOL;
```

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

// Dentro de: public static void main(String[] args) throws Exception
HttpClient cliente = HttpClient.newHttpClient();
HttpRequest peticion = HttpRequest.newBuilder()
    .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contexto"))
    .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
    .GET()
    .build();
HttpResponse<String> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString());
System.out.println(respuesta.statusCode() + " " + respuesta.body());
```

```bash-cli
# Una sola vez: guarda tu API Key de pruebas en el CLI (te la pide sin mostrarla).
ecuafact login --entorno sandbox

# Resultado esperado: tu integración y sus contribuyentes, en tabla.
ecuafact cuenta --entorno sandbox
```

### Resultado esperado

Si la API Key y la IP son correctas, recibes `200 OK` con tu integración y tus
contribuyentes:

```json
{
  "idCliente": "1f2e3d4c-5b6a-4789-9012-abcdef012345",
  "nombre": "Integracion de ejemplo",
  "contribuyentes": [
    {
      "identificacion": "0123456789001",
      "puedeEmitir": true,
      "puedeRecibir": true,
      "tiposComprobante": [
        "01",
        "03",
        "04",
        "05",
        "06",
        "07"
      ],
      "marcaBlanca": false
    }
  ]
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| `idCliente` | string (UUID) | Identificador de tu integración. Inclúyelo al pedir soporte. |
| `nombre` | string | Nombre de tu integración. |
| `contribuyentes` | array | Contribuyentes habilitados para tu API Key en este ambiente. Puede venir vacío si aún no tienes ninguno habilitado. |
| `contribuyentes[].identificacion` | string | Identificación completa del contribuyente (para un RUC, sus 13 dígitos). Es el valor que usas en la ruta `{identificacion}` y en `infoTributaria.ruc`. |
| `contribuyentes[].puedeEmitir` | boolean | `true` si puedes emitir comprobantes para este contribuyente. |
| `contribuyentes[].puedeRecibir` | boolean | Indica si el contribuyente tiene habilitada la recepción. |
| `contribuyentes[].tiposComprobante` | array de string | Tipos de comprobante habilitados (`tipoDocumento`): `01`, `03`, `04`, `05`, `06`, `07`. |
| `contribuyentes[].marcaBlanca` | boolean | `true` si el contribuyente es de marca blanca y sus comprobantes no tienen RIDE. Más detalle en [Contexto](/v1/guias/consulta-contexto). |

Sabes que funcionó cuando el estado HTTP es 200 y ves tus contribuyentes. Si
recibes un 401 con el `codEstado` 3009 (`credenciales_invalidas`) o un 403 con
el `codEstado` 3010 (`ip_no_autorizada`), revisa
[Errores de autenticación](#errores-de-autenticacion).

## Obtén tu API Key

Puedes conseguir una API Key de distintas maneras, según si quieres probar, si
ya tienes acceso al portal o si vas a producción.

| Situación | Cómo la obtienes |
|---|---|
| Quieres probar y no tienes cuenta | [Crea tu cuenta](/v1/guias/sandbox) en `https://portal.mynexusapi.com/sandbox`. Al terminar el alta, ingresa al portal y sigue la fila siguiente. |
| Tu cuenta está en pruebas | Abre **Pruebas** en el Portal del Cliente y pulsa **Generar** en "API Key de pruebas" (si ya tienes una, pulsa **Rotar**). La API Key se muestra una sola vez. |
| Necesitas producción | Desde el Portal del Cliente, en **Pasar a producción**, como se explica en [Sandbox de pruebas](/v1/guias/sandbox#pasar-a-produccion). La API Key de producción se muestra una sola vez. |
| Ya estás en producción | Entra a **Cuenta > API Keys** y pulsa **Crear API Key**. Escribe un nombre que identifique su uso, por ejemplo `ERP produccion`. |

Al crear una clave en el portal, la API Key completa **se muestra una sola
vez**, así que cópiala en ese momento a tu gestor de secretos. Si la pierdes, no
se puede recuperar; en ese caso, crea otra y revoca la anterior.

### Scopes y RUC de una API Key

Cada API Key tiene dos límites independientes:

- **Scopes:** qué acciones puede hacer.
- **RUC permitidos:** sobre qué contribuyentes puede actuar.

Una API Key con `*` en scopes puede usar todos los servicios; una API Key con una
lista solo puede usar esos servicios. Lo mismo aplica a `ruc`: `*` significa
todos los RUC y una lista limita la API Key a esas identificaciones. La clave que
se crea con un sandbox queda limitada a su RUC y a los scopes de integración;
no puede emitir ni consultar otro contribuyente.

En el Portal del Cliente, al crear una clave en **Cuenta > API Keys**, eliges los
servicios y los RUC, y la tabla de claves muestra el alcance de cada una. Si no
limitas ninguno, la clave puede usar todos los servicios y todos los RUC. Para
cambiar los permisos de una clave existente, crea una nueva y revoca la anterior.

Los scopes disponibles son:

| Scope | Permite |
|---|---|
| `cuenta:leer` | Consultar el contexto y el consumo. |
| `comprobantes:leer` | Consultar operaciones y comprobantes emitidos, y descargar el RIDE y el XML. |
| `comprobantes:emitir` | Emitir y validar comprobantes. |
| `sri:consultar` | Consultar contribuyentes, establecimientos, identificaciones y claves de acceso. |
| `perfil:leer` | Ver el perfil del emisor. |
| `perfil:escribir` | Actualizar el perfil del emisor y su logo. |
| `webhooks:leer` | Ver destinos, entregas e intentos. |
| `webhooks:gestionar` | Crear, editar, rotar secreto, pausar, reanudar y deshabilitar destinos. |
| `webhooks:probar` | Enviar el evento de prueba. |
| `webhooks:reintentar` | Reenviar una entrega. |

Una API Key limitada a un RUC no puede ver ni administrar destinos de otro RUC ni
un destino para todos los RUC. Si intentas una operación fuera de su alcance, la
API responde 403 con el `codEstado` 3011 (`acceso_denegado`).

> [!WARNING]
> La API Key permite emitir comprobantes a nombre de tus contribuyentes. No la
> pegues en tickets, chats, repositorios ni capturas de pantalla.

## Guarda la API Key

Te recomendamos que tu código lea la API Key desde fuera del código fuente.
Todos los ejemplos de esta documentación la leen de la variable de entorno
`ECUAFACT_API_KEY`, y la tabla muestra cómo definirla según dónde corre tu
aplicación.

| Dónde | Cómo |
|---|---|
| Tu equipo (desarrollo) | Define la variable en la sesión: `export ECUAFACT_API_KEY="..."` (Linux/macOS) o `$env:ECUAFACT_API_KEY="..."` (PowerShell). Si usas un archivo `.env`, agrégalo a `.gitignore`. |
| Servidor o contenedor | Define una variable de entorno del servicio (systemd, Docker, Kubernetes Secret o la configuración de la aplicación en tu proveedor de nube). |
| Producción | Usa un gestor de secretos que inyecte el valor al iniciar la aplicación, por ejemplo Azure Key Vault, AWS Secrets Manager, Google Secret Manager o HashiCorp Vault. |
| .NET en desarrollo | Ejecuta `dotnet user-secrets set "Ecuafact:ApiKey" "..."` y léela desde la configuración. |

Además, te recomendamos estas tres prácticas:

- Usa la API Key **solo en tu backend**. Nunca la pongas en el navegador, en una
  app móvil ni en una aplicación de escritorio que entregues a terceros, porque
  cualquiera podría extraerla.
- No la escribas en logs. Si registras cabeceras, enmascara `X-Api-Key`.
- Usa una API Key distinta por sistema, por ejemplo una para el ERP y otra para
  la tienda en línea. Así puedes revocar una sin detener la otra.

## Rota o revoca una API Key

Rota la API Key si se filtró, si una persona con acceso deja el equipo o cuando
lo pida tu política de seguridad. La rotación no corta el servicio si sigues
este orden:

1. En el portal, entra a **Cuenta > API Keys**, pulsa **Crear API Key** y copia la
   nueva API Key.
2. Actualiza el secreto en tu servidor y reinicia o recarga la aplicación.
3. Verifica con `GET /v1/contexto` que la nueva API Key responde 200.
4. En **Cuenta > API Keys**, abre el menú de la clave anterior y pulsa **Revocar**.

La revocación tarda hasta 30 segundos en aplicarse. Pasado ese tiempo, la clave
revocada recibe un 401 con el `codEstado` 3009 (`credenciales_invalidas`).

> [!WARNING]
> Si sospechas que tu API Key se filtró, revócala de inmediato aunque tu servicio
> se detenga unos minutos. Quien la tenga podría emitir comprobantes con validez
> fiscal si también controla una IP registrada.

## Registra tu IP

En producción, puedes registrar en la lista de **IP permitidas** de tu
integración las IP desde las que llamas a la API. Si una petición llega desde
una IP que no está en la lista, la API la rechaza con un 403 y el `codEstado`
3010 (`ip_no_autorizada`), aunque la API Key sea correcta. El sandbox no exige
IP registrada.

### Averigua tu IP pública de salida

La IP que importa es la que ve la API, no la de tu red interna. Las direcciones
que empiezan por 192.168, 10 o 172.16 a 172.31 son privadas y nunca llegan a la
API. Para conocer la IP pública, ejecuta este comando **desde el mismo
servidor** que llamará a la API:

```bash
curl -4 https://ifconfig.me   # IP publica IPv4
curl -6 https://ifconfig.me   # IP publica IPv6 (si tu servidor tiene IPv6)
```

| Tu caso | Qué IP registrar |
|---|---|
| Servidor propio con IP fija | La IP pública fija que te asignó tu proveedor de Internet. |
| Oficina o red con NAT | La IP pública del router o firewall por el que sale el tráfico. Todos los equipos detrás del NAT comparten esa IP. |
| Nube (máquina virtual) | Asigna una IP pública estática (IP elástica o reservada). La IP dinámica por defecto puede cambiar al reiniciar. |
| Nube (funciones, contenedores administrados, PaaS) | Estos servicios salen por IP que cambian. Configura una salida fija (NAT gateway con IP estática o la opción de IP de salida dedicada de tu proveedor) y registra esa IP. |
| Tu equipo de desarrollo (casa u oficina) | La IP pública de tu conexión. Suele cambiar, así que vuelve a revisarla si empiezas a recibir el `codEstado` 3010 (`ip_no_autorizada`). |

### Formatos admitidos

Para registrar una IP, entra en el Portal del Cliente a **Cuenta > IP
permitidas** y pulsa **Agregar**. Para borrar una IP que ya no usas, pulsa
**Quitar**. La tabla muestra qué formatos acepta la lista.

| Formato | Ejemplo | Admitido |
|---|---|---|
| IPv4 exacta | `203.0.113.10` | Sí |
| IPv6 exacta | `2001:db8::10` | Sí |
| Rango IPv4 en notación CIDR | `203.0.113.0/24` | Sí |
| Rango IPv6 en notación CIDR | `2001:db8::/64` | Sí, con prefijo de /32 o más largo. |
| Cualquier dirección (`0.0.0.0/0` o `::/0`) | `0.0.0.0/0` | No |
| Nombre de dominio | `servidor.midominio.com` | No |

Si no registras ninguna IP, en producción solo funcionan las API Key limitadas a
servicios y RUC concretos (no a todos). En cuanto registras una IP, la lista se
aplica a todas tus API Key.

Usa **Probar** en la misma pantalla para comprobar si una IP queda cubierta por
tu lista. Registra solo las IP que de verdad llaman a la API, porque cada IP o
rango que agregas es un punto de entrada más para tu API Key.

> [!NOTE]
> Si tu servidor tiene IPv4 e IPv6, la conexión puede salir por cualquiera de las
> dos. Registra ambas, o fuerza IPv4 en tu cliente HTTP (por ejemplo `curl -4`).

La API valida la IP de la conexión que recibe, así que enviar cabeceras como
`X-Forwarded-For` no cambia la IP que se valida.

## Límite de intentos fallidos

Para proteger tu API Key de quien intenta adivinarla, limitamos **por IP de
origen** los intentos de autenticación fallidos, es decir, las peticiones
rechazadas con un 401 y el `codEstado` 3009 (`credenciales_invalidas`) o con un
403 y el `codEstado` 3010 (`ip_no_autorizada`).

| Regla | Valor |
|---|---|
| Intentos fallidos permitidos | 20 por minuto, por IP. En IPv6 se cuentan juntas todas las direcciones del mismo prefijo /64. |
| Ventana | El minuto de reloj, de hh:mm:00 a hh:mm:59. El contador vuelve a cero al empezar el minuto siguiente. |
| Al superar el límite | Toda petición desde esa IP recibe un 429 con el `codEstado` 5005 (`limite_solicitudes`) hasta que termine el minuto, **sin importar qué API Key envíe**, aunque sea correcta. |
| Cuánto esperar | Los segundos que indica la cabecera `Retry-After`. |
| Reinicio | El contador no se reinicia con una autenticación correcta: expira al terminar el minuto. |

Un bucle que reintenta con una API Key equivocada termina bloqueando tu propia
IP. Si recibes el `codEstado` 3009 (`credenciales_invalidas`) o el 3010
(`ip_no_autorizada`), corrige la causa antes de reintentar. El detalle
de los límites está en [Límite de request](/v1/guias/limite-de-request).

## Errores de autenticación

| `codEstado` | HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| 3009 (`credenciales_invalidas`) | 401 | Falta la cabecera `X-Api-Key`, está mal escrita o la API Key no existe, está revocada, venció o pertenece a otro ambiente. | Revisa el nombre de la cabecera y que copiaste la API Key completa, con el punto. Si la revocaste, crea otra. Si es de otro ambiente, usa la clave que corresponde a la URL. |
| 3010 (`ip_no_autorizada`) | 403 | En producción, la API Key es válida pero la petición llega desde una IP que no está en **IP permitidas**, o la API no pudo identificar la IP de origen. En sandbox no ocurre por IP. | Averigua tu IP pública de salida y agrégala en **Cuenta > IP permitidas**. Si usas un proxy, llama directo a la URL de la API. Si persiste, abre un ticket con el valor de `X-Correlation-Id`. |
| 3011 (`acceso_denegado`) | 403 | La autenticación fue correcta, pero el contribuyente de la ruta o el tipo de comprobante no están habilitados. | Revisa `GET /v1/contexto` y usa una `identificacion` y un `tipoDocumento` que aparezcan ahí; la misma `identificacion` va en `infoTributaria.ruc`. |
| 5005 (`limite_solicitudes`) | 429 | Superaste 20 intentos fallidos por minuto desde la misma IP, o el límite de solicitudes por minuto de tu integración. | Espera los segundos que indica `Retry-After` y corrige la API Key o la IP antes de reintentar. |

### Cuándo aparece 3009

| Caso | Qué revisar |
|---|---|
| No enviaste `X-Api-Key` | La cabecera debe viajar en todas las peticiones a `/v1`. |
| La clave está mal formada | Debe tener las dos partes separadas por un punto (`prefijo.secreto`), sin espacios ni saltos de línea. Vuelve a copiarla desde **Cuenta > API Keys**. |
| La clave fue revocada, venció o se eliminó | En **Cuenta > API Keys** la clave aparece como **Revocada** o **Vencida**. Crea una nueva. |
| La clave pertenece a otro ambiente | Pruebas y producción usan claves distintas. Usa la clave del ambiente de la URL. |
| La clave no existe | Revisa que hayas copiado la clave completa y que estés usando la integración correcta. |

La IP no se informa con 3009. En producción, si la clave es válida y la IP no está permitida, la respuesta es 403 con el `codEstado` 3010 (`ip_no_autorizada`). El sandbox no exige IP registrada.

### Cuándo aparece 3010

| Caso | Qué revisar |
|---|---|
| La IP no está en **IP permitidas** | Averigua tu IP pública de salida y agrégala en **Cuenta > IP permitidas**. |
| La IP cambió por VPN, nube o proxy | Registra la IP de salida real o fuerza una salida fija. |
| La API no pudo identificar la IP | Llama directo a la URL de la API, sin proxies que oculten el origen. |

El catálogo completo de `codEstado` está en [Errores](/v1/guias/errores#catalogo-de-codestado).

Si el problema persiste, abre un ticket en [soporte.ecuafact.com](https://soporte.ecuafact.com/). También puedes consultar el [centro de ayuda](https://ecuafact.com/ayuda/) o escribir por [WhatsApp](https://wa.me/593988315544). Horario: lunes a viernes, 09:00-18:00 GMT-5. Primera respuesta: 1 día hábil; producción caída: 4 horas.

## Siguientes pasos

- [Ambientes y contribuyentes](/v1/guias/ambientes): elige la URL correcta y la `identificacion` que usarás en las rutas.
- [Primeros pasos](/v1/guias/primeros-pasos): emite tu primer comprobante en pruebas.
- [Límite de request](/v1/guias/limite-de-request): cuántas solicitudes por minuto puedes hacer y cómo leer `Retry-After`.
- [Errores](/v1/guias/errores): todos los códigos y qué hacer ante cada uno.
