> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pos.terominds.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticación con API keys

> Usá una API key de la empresa para llamar a la API de administración sin iniciar sesión en el navegador.

## Qué es

Las API keys permiten que un script, una integración o una carga inicial hablen con la API de administración de **una empresa**. No reemplazan el ingreso al back office: sirven para automatizar tareas como listar productos, importar un CSV o actualizar medios de pago.

Cada clave pertenece a un solo comercio. Tero guarda un hash y un prefijo visible; la clave completa se muestra una sola vez al crearla.

## Dónde está

La URL base de la API es:

```
https://pos-api.terominds.com/api
```

En staging:

```
https://pos-api.stg.terominds.com/api
```

Llamá a `pos-api` en forma directa. El sitio `teropos.com.ar` (antes `pos.terominds.com`) es el back office y no acepta estas claves en el navegador.

Creá y revocá las claves en **Back office → Configuración → Equipo → API keys**. El procedimiento está en [Crear y revocar API keys](https://docs.pos.terominds.com/api/crear-y-revocar.md).

## Cómo se usa

Enviá la clave en el encabezado `Authorization` como Bearer. El formato es `tero_live_<prefijo>_<secreto>`.

```bash theme={null}
export TERO_API_KEY='tero_live_aabbccdd_xxxxxxxx'
export TERO_TENANT_ID='00000000-0000-0000-0000-000000000001'
export TERO_API='https://pos-api.terominds.com/api'

curl -sS "$TERO_API/admin/tenants/$TERO_TENANT_ID/catalog" \
  -H "Authorization: Bearer $TERO_API_KEY" \
  -H "Accept: application/json"
```

El `tenantId` es el identificador de la empresa. Lo ves en la URL del back office: `/admin/tenants/<tenantId>/...`.

**1. Creá una clave**

En **Configuración → Equipo → API keys** elegí el [alcance](https://docs.pos.terominds.com/api/alcances.md) y copiá la clave completa.

**2. Guardala fuera del repositorio**

Usá una variable de entorno o un gestor de secretos. No la subas a git ni la pegues en un chat.

**3. Llamá a pos-api**

Usá `https://pos-api.terominds.com/api` y el encabezado `Authorization: Bearer …`.

## Configuración

| Encabezado | Valor |
| - | - |
| `Authorization` | `Bearer tero_live_<prefijo>_<secreto>` |
| `Accept` | `application/json` |
| `Content-Type` | `application/json` en POST y PUT |

No hace falta `X-Tero-Origin-Secret`. Ese encabezado lo envía solo el back office para las sesiones del navegador. Una API key con el formato correcto alcanza para entrar a `pos-api`.

Una sesión de cookies **no** alcanza para llamar a `pos-api` en forma directa. Eso evita que una cookie robada se use fuera del sitio.

## Errores

| Código | `error` | Qué significa |
| - | - | - |
| 401 | `unauthorized` | Falta autenticación (no hay clave ni sesión). |
| 401 | `invalid_api_key` | La clave no existe o el secreto no coincide. |
| 401 | `api_key_revoked` | La clave fue revocada. |
| 401 | `api_key_expired` | La clave venció. |
| 403 | `insufficient_scope` | Una clave de solo lectura intentó un método que no es GET. |
| 403 | `forbidden` | La clave no corresponde a esa empresa, o el endpoint es solo de plataforma. |
| 429 | `rate_limited` | Demasiadas llamadas. Esperá un minuto y reintentá. |

La API de administración está acotada a la empresa de la clave. Los endpoints de superadmin (crear empresas, flota global, releases) no aceptan API keys.

## Tips y advertencias

> [!WARNING]
>
> La clave completa se muestra **una sola vez**. Si la perdés, revocala y creá otra. Tero nunca vuelve a mostrar el secreto.

* Preferí una clave de **solo lectura** si el script no necesita cambiar datos.
* Si una automatización deja de usarse, revocala.
* El `tenantId` de la URL tiene que ser el de la empresa dueña de la clave.

## Relacionado

> **[Alcances](https://docs.pos.terominds.com/api/alcances.md)**
>
> Lectura o lectura y escritura.

> **[Crear y revocar](https://docs.pos.terominds.com/api/crear-y-revocar.md)**
>
> Desde el back office.

> **[Ejemplos](https://docs.pos.terominds.com/api/ejemplos.md)**
>
> Productos, CSV, fotos y cobros.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.