# Autenticación

> Crea una clave de API en MINDO y úsala en cada llamada.

Cada llamada a la API lleva una **clave de API** en el encabezado `Authorization`:

```http
Authorization: Bearer etk_live_Q7mJx2VbR9tLw4Nc8ZpK1sHd6YfA3uEg
```

Las claves empiezan con `etk_live_` y pertenecen a una cuenta (workspace). Todo lo que hagas con una clave queda en esa cuenta: los mensajes aparecen en el chat, los contactos en **Contactos**, y así.

## Crear una clave

<Note>
  Necesitas un plan **Escala** o **Enterprise** y ser **Dueño** o **Administrador** de la cuenta. Los agentes no ven la sección de API.
</Note>

<Steps>
  <Step title="Entra a Ajustes › API y webhooks">
    En [app.mindo.ar](https://app.mindo.ar), abre **Ajustes** (abajo a la izquierda) y elige la pestaña **API y webhooks**.
  </Step>
  <Step title="Toca Nueva clave y ponle un nombre">
    Usa un nombre que te diga para qué es, por ejemplo _Tienda online_, _CRM_ o _Zapier_. Te conviene una clave por integración: si una se filtra, la revocas sin cortar las demás. Puedes tener hasta 10 claves vigentes en Escala y 50 en Enterprise.

    <Frame>
      <img src="/images/api/nueva-clave.png" alt="Diálogo Nueva clave de API con el nombre Tienda online" />
    </Frame>
  </Step>
  <Step title="Copia la clave y guárdala en un lugar seguro">
    La clave completa se muestra **una sola vez**. Cópiala con el botón de copiar y guárdala en las variables de entorno de tu servidor o en tu gestor de contraseñas. Después toca **Ya la guardé**.

    <Frame>
      <img src="/images/api/clave-creada.png" alt="Diálogo Tu clave de API mostrando la clave completa una sola vez" />
    </Frame>
  </Step>
  <Step title="Listo: ya puedes usarla">
    En la lista ves el nombre, el comienzo de la clave y cuándo se usó por última vez.

    <Frame>
      <img src="/images/api/lista-claves.png" alt="Lista de claves de API con la clave Tienda online" />
    </Frame>
  </Step>
</Steps>

## Probar la clave

`GET /me` te devuelve la cuenta de la clave. Si responde `200`, está todo bien.

<CodeGroup>

```bash curl
curl https://app.mindo.ar/api/v1/me \
  -H "Authorization: Bearer $MINDO_API_KEY"
```

```javascript Node
const res = await fetch("https://app.mindo.ar/api/v1/me", {
  headers: { Authorization: `Bearer ${process.env.MINDO_API_KEY}` },
})
console.log(await res.json())
```

```python Python
import os, requests

res = requests.get(
    "https://app.mindo.ar/api/v1/me",
    headers={"Authorization": f"Bearer {os.environ['MINDO_API_KEY']}"},
)
print(res.json())
```

```php PHP
<?php
$ch = curl_init("https://app.mindo.ar/api/v1/me");
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("MINDO_API_KEY")],
  CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);
```

</CodeGroup>

```json Respuesta
{
  "workspace": {
    "id": "01a0d456-02d1-75db-80d0-46d30c775e9d",
    "name": "Café Aurora",
    "plan": "escala"
  }
}
```

## Con qué permisos actúa una clave

- Una clave actúa **como la persona que la creó**, con permisos de administrador. Los mensajes que mandes por la API aparecen en el chat como enviados por esa persona.
- Si esa persona ya no está en la cuenta, la clave sigue funcionando y actúa como el dueño.
- La clave funciona mientras la cuenta tenga un plan con API. Si el plan baja o la prueba termina, las llamadas responden `402` (y los webhooks dejan de enviarse) hasta que vuelvas a un plan con API. Las claves no se borran.

## Revocar una clave

En **Ajustes › API y webhooks**, toca **Revocar** al lado de la clave. Deja de funcionar al instante: la próxima llamada con esa clave responde `401`.

<Warning>
  Trata la clave como una contraseña. **Nunca** la pongas en el código de una página web, una app móvil o un repositorio público: cualquiera que la vea podría mandar mensajes en tu nombre. Llama a la API siempre desde tu servidor.
</Warning>

## Errores de autenticación

| Código | Cuándo pasa |
| --- | --- |
| `401` | Falta el encabezado `Authorization`, la clave no empieza con `etk_`, no existe o fue revocada. |
| `402` | La clave es válida, pero el plan de la cuenta no incluye la API, la prueba terminó o la cuenta está pausada. |
| `429` | Superaste el tope por minuto o el cupo mensual de tu plan, o hubo demasiados intentos con claves inválidas desde tu IP. Mira [Límites](/api/limites). |

```json 401
{ "error": "La clave de API no es válida o fue revocada.", "cause": null }
```

Más detalles en [Errores](/api/errores).