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

# Autenticación

> Autentica tus peticiones a la TapiPay Facade API con tu API key y tu Token TAPI, y prueba tu primer endpoint.

La Facade API usa **dos credenciales** en cada petición: tu **API key** (header `x-api-key`) y tu **Token TAPI** (header `x-authorization-token`). Las dos son obligatorias: si falta cualquiera, la petición se rechaza con `401`.

## Las dos credenciales

<ResponseField name="x-api-key" type="string" required>
  La API key de tu integración en el API Gateway de Tapi. Te la provee Tapi y es **distinta por ambiente** (desarrollo, homologación, producción). Identifica a tu aplicación y controla el acceso al gateway.
</ResponseField>

<ResponseField name="x-authorization-token" type="string" required>
  Tu **Token TAPI** (un JWT), el mismo que ya utilizas con el resto de la plataforma de Tapi. Se envía **sin** el prefijo `Bearer`.
</ResponseField>

<Warning>
  El token va en `x-authorization-token`, **no** en el estándar `Authorization: Bearer`, y sin el prefijo "Bearer". Es un header propio de Tapi para mantener compatibilidad con el resto de la plataforma.
</Warning>

## Cómo obtener tu Token TAPI

El Token TAPI (un JWT) se obtiene del login de Tapi, el mismo que ya usas en el resto de la plataforma. Envía tus credenciales y recibirás un `accessToken`:

```bash theme={null}
curl --request POST \
  --url 'https://login.<ambiente>.tapila.cloud/login' \
  --header 'x-api-key: TU_API_KEY_DE_LOGIN' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientUsername": "TU_USUARIO",
    "password": "TU_PASSWORD"
  }'
```

La respuesta incluye el `accessToken` (tu Token TAPI) y un `refreshToken`:

```json theme={null}
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

<Note>
  El `accessToken` vence a las \~4 horas. Cuando expire, repite el login (o usa el `refreshToken` con el flujo estándar de Tapi). La `x-api-key` del login es la de tu integración y **no** es la misma que usas contra la Facade.
</Note>

## Prueba un endpoint

<Tabs>
  <Tab title="Desde el playground">
    En el [API Reference](/api-reference), abre cualquier endpoint y usa el botón **Send**:

    1. Elige el **servidor** en el selector.
    2. Pega tu `x-api-key` y tu `x-authorization-token` en los campos de autenticación.
    3. Completa los parámetros y presiona **Send**.

    Tus credenciales quedan guardadas **solo en tu navegador** y se reutilizan en todos los endpoints.
  </Tab>

  <Tab title="Con curl">
    ```bash theme={null}
    curl --request GET \
      --url '<BASE_URL>/contacts?page=1&limit=10' \
      --header 'x-api-key: TU_API_KEY' \
      --header 'x-authorization-token: TU_TOKEN_TAPI'
    ```

    Reemplaza `<BASE_URL>` por la URL del ambiente contra el que pruebas.
  </Tab>
</Tabs>

<Warning>
  Nunca compartas ni subas a un repositorio tu `x-api-key` ni tu token: son credenciales sensibles. En el playground viven solo en tu navegador; en curl, pásalas como variables de entorno.
</Warning>

## Qué resuelve tu token por ti

A partir de tu token, Tapi identifica tu cuenta y resuelve internamente todo el modelo interno (company, modalities, etc.). Tú trabajas con conceptos de negocio claros y nunca necesitas enviar ni conocer esos datos internos.

## Errores de autenticación

Cuando la API key o el token faltan, son inválidos o están vencidos, la API responde con `401` y esta estructura:

```json theme={null}
{
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Token TAPI faltante o inválido"
  },
  "requestId": "req_a1b2c3d4"
}
```

Todos los errores de la API siguen la misma forma: un objeto `error` con `code` y `message`, más un `requestId` que puedes compartir con soporte para rastrear la petición.

## Token vencido

Si tu token venció, refréscalo con el mismo flujo que ya usas para el resto de la API de Tapi y reintenta la petición. La Facade no tiene un mecanismo de refresco propio: reutiliza el del ecosistema de Tapi.

<Note>
  Consejo: si usas un SDK de Tapi, los headers `x-api-key` y `x-authorization-token` ya vienen preconfigurados, así que no tienes que armarlos a mano.
</Note>