# Autenticación y llaves

> Cómo se identifica su sistema con su llave secreta, cómo limitarla a ciertos emisores, a solo lectura o a un plazo, y cómo cambiarla sin cortes.

Cada solicitud lleva su llave secreta en el encabezado `Authorization`:

```bash tab="cURL"
curl https://api.fiscalisto.com/v1/account \
  -H "Authorization: Bearer $FISCALISTO_API_KEY"
```

```ts tab="TypeScript"
import { Fiscalisto } from "fiscalisto";

// La llave viene de FISCALISTO_API_KEY.
const fiscalisto = new Fiscalisto();

const account = await fiscalisto.account.get();
```

```python tab="Python"
from fiscalisto import Fiscalisto

# La llave viene de FISCALISTO_API_KEY.
fiscalisto = Fiscalisto()

account = fiscalisto.account.get()
```

```php tab="PHP"
<?php

use Fiscalisto\Fiscalisto;

// La llave viene de FISCALISTO_API_KEY.
$fiscalisto = new Fiscalisto();

$account = $fiscalisto->account->get();
```

```go tab="Go"
package main

import (
	"context"
	"fmt"
	"log"

	fiscalisto "fiscalisto.com/go"
)

func main() {
	// La llave viene de FISCALISTO_API_KEY.
	client, err := fiscalisto.NewClient("")
	if err != nil {
		log.Fatal(err)
	}
	ctx := context.Background()

	account, err := client.Account.Get(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(account.ID)
}
```

```java tab="Java"
import com.fiscalisto.FiscalistoClient;

// La llave viene de FISCALISTO_API_KEY.
var fiscalisto = new FiscalistoClient();

var account = fiscalisto.account().get();
System.out.println(account.getId());
```

```csharp tab="C#"
using Fiscalisto;

// La llave viene de FISCALISTO_API_KEY.
var fiscalisto = new FiscalistoClient();

var account = await fiscalisto.Account.GetAsync();
```

También se acepta como usuario de HTTP Basic, sin contraseña (`curl -u "$FISCALISTO_API_KEY:"`), para las herramientas que solo saben de esa forma.

## Formato

Una llave es `fk_test_` o `fk_live_` seguido de 40 letras y números. El prefijo dice el modo (vea [Pruebas y producción](https://fiscalisto.com/docs/api/pruebas-y-produccion)). Fiscalisto guarda solo su huella: si la pierde, cree otra.

## Dónde guardarla

- En una variable de entorno o en el gestor de secretos de su servidor, nunca en el código ni en el repositorio.
- Nunca en el navegador ni en una app que se instala en teléfonos: quien la tenga timbra a su nombre. La API no contesta a solicitudes del navegador (las rechaza con `browser_not_supported`); la excepción es **Probar** en la referencia de esta documentación, y solo con llaves de pruebas.
- Una llave por sistema o por ambiente, con un nombre que diga dónde vive, para revocar solo la que se filtró.

## Llaves limitadas a algunos emisores

Al crear una llave en **Desarrolladores › Llaves** puede marcar **Solo para algunos emisores**. Esa llave solo ve y timbra con esos RFC; lo que toca a otro emisor, crea emisores nuevos o es de toda la cuenta (como los webhooks) responde `403` con `key_restricted`. Sirve, por ejemplo, para darle a cada sucursal o a cada cliente de su plataforma una llave que solo factura con su RFC.

## Llaves de solo lectura

En **Permisos** elija **Solo lectura** para una llave que consulta y no cambia nada: todas las solicitudes `GET` (facturas, PDF, XML, saldo, catálogos, eventos) y tres `POST` que solo revisan: `POST /v1/tax_ids/validate`, `POST /v1/sat_lists/check` y `POST /v1/payroll_receipts/preview`. Lo demás (timbrar, cancelar, enviar, crear o cambiar datos) responde `403` con `key_read_only`. Sirve para un tablero, un reporte o la herramienta de su equipo de soporte. Se puede combinar con **Solo para algunos emisores**.

## Llaves que vencen

En **Vence** elija si la llave deja de funcionar en 30 días, 90 días, 6 meses o 1 año (**Nunca**, si no). Le avisamos por correo 7 días y 1 día antes, a los propietarios y administradores de la cuenta. Al vencer responde `401` con `invalid_api_key`. **Cambiar llave** le da una nueva con el mismo plazo, contado desde ese día. `GET /v1/account` dice de la llave que hizo la solicitud si es de solo lectura (`key.read_only`) y cuándo vence (`key.expires_at`), para que su sistema avise antes.

## Elegir el emisor

Lo que crea comprobantes, clientes o productos lleva el emisor (`iss_…`) en `issuer`, en el cuerpo; las listas lo llevan en la consulta (`?issuer=iss_…`). Si la cuenta, o la llave, tiene un solo emisor, puede omitirlo. Si tiene varios y no lo manda, la API responde `issuer_required`. Los ids de lo demás (`inv_…`, `cus_…`) ya dicen de qué emisor son.

## Cambiar una llave sin cortes

En **Desarrolladores › Llaves** elija **Cambiar llave** en su menú. Le damos una nueva con el mismo nombre y los mismos permisos, y usted elige cuándo deja de servir la anterior: ahora mismo, en 1 hora, en 24 horas o en 7 días. Ponga la nueva en su servidor dentro de ese plazo. Si una llave se filtró, cámbiela con **Ahora mismo** o revóquela.

## Límites

- Hasta 50 llaves por modo.
- Crear llaves de producción pide verificación en dos pasos del usuario.
- Una dirección IP que manda muchas llaves inválidas seguidas recibe `429` por un minuto; nunca afecta a las llaves válidas.

## Errores de autenticación

| Código | Qué pasó |
| --- | --- |
| [`missing_api_key`](https://fiscalisto.com/docs/api/errores#missing_api_key) | No llegó el encabezado `Authorization`. |
| [`invalid_api_key`](https://fiscalisto.com/docs/api/errores#invalid_api_key) | La llave no existe, se revocó o ya expiró. |
| [`key_restricted`](https://fiscalisto.com/docs/api/errores#key_restricted) | La llave está limitada a otros emisores. |
| [`key_read_only`](https://fiscalisto.com/docs/api/errores#key_read_only) | La llave es de solo lectura y la solicitud cambia algo. |
| [`livemode_mismatch`](https://fiscalisto.com/docs/api/errores#livemode_mismatch) | El objeto es del otro modo. |