# Autenticación

> Claves de API, alcances de lectura y escritura, revocación de claves y seguridad.

La API utiliza claves de API secretas. Cada clave pertenece a un espacio de trabajo.

## Envíe la clave

Coloque la clave en el encabezado `Authorization` como un token de portador:

```http
GET /api/v1/workspace HTTP/1.1
Host: tradecatalog.app
Authorization: Bearer tc_live_Xk2…
```

```bash
curl https://tradecatalog.app/api/v1/workspace \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"
```

Las claves siempre comienzan con `tc_live_`. No hay claves de prueba: pruebe las cosas en un espacio de trabajo con datos de muestra, o lea antes de escribir.

## Crear una clave

Solo el **propietario** del espacio de trabajo o un **administrador** puede crear claves, en **Configuración → API**.

| Configuración       | Qué significa                                                                                                         |
| ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Nombre              | Su etiqueta, por ejemplo, “sincronización de stock de Sage”. Mostrado en Configuración y en el registro de actividad. |
| Solo lectura        | Solo solicitudes `GET`.                                                                                               |
| Lectura y escritura | También `PUT /products`, `PUT /customers` y `PATCH /orders/{id}`.                                                     |

La clave se muestra **una vez**. Solo almacenamos un hash SHA-256, por lo que nadie en TradeCatalog puede verla nuevamente. La configuración muestra los primeros caracteres (como `tc_live_Xk2m…`) para que pueda distinguir las claves.

Un espacio de trabajo puede tener hasta **20 claves activas**. Asigne una clave a cada sistema, para que pueda revocar una sin afectar a las demás.

## ¿Quién puede tener claves

El espacio de trabajo necesita uno de estos para crear claves:

- una suscripción activa
- una prueba Pro
- una cuenta piloto (acordada con Happy Webs)

No se pueden crear o usar claves en espacios de trabajo de demostración.

Si la suscripción caduca, tiene 14 días de gracia. Después de eso, el espacio de trabajo vuelve a Free. Las claves existentes aún pueden leer, pero las escrituras de API fallan con `403 read_only` hasta que Pro esté activo nuevamente. Las ediciones del catálogo y las órdenes de compradores en la aplicación siguen funcionando.

## Qué puede hacer una clave

Una clave actúa con las **permisos de la persona que la creó**, tal como son ahora. Una clave creada por un propietario o administrador puede leer a cada cliente, los precios de cada cliente, cada orden y el registro de actividad. Trátala como la contraseña de esa persona. Una clave creada por alguien limitado a sus clientes asignados o regiones solo ve esos clientes y sus órdenes, precios y actividad; cualquier otro cliente u orden devuelve `404`, lo mismo que uno que no existe, y los cambios de precio devuelven `403`.

Si esa persona luego recibe un rol más estrecho, la clave se estrecha con ella: un write que el nuevo rol no permite falla con `403 forbidden`, lo mismo que en la aplicación. Si abandona el espacio de trabajo, la clave deja de funcionar con `401 key_owner_removed`. Cree una nueva clave desde alguien que aún tenga acceso.

## Último uso y revocación

La configuración muestra cuándo se usó cada clave por última vez (actualizado como máximo una vez por hora). Elija **Revocar** para detener inmediatamente una clave. La siguiente solicitud con ella obtiene `401 unauthorized`. Las claves revocadas no se pueden restaurar.

## Quién se registra los cambios

Las escrituras aparecen en el registro de actividad del espacio de trabajo como `API key “Sage stock sync”`. Los cambios de estado de las órdenes se registran contra la persona que creó la clave.

## Mantenga las claves seguras

- Mantenga las claves en su servidor, en variables de entorno o en un gestor de secretos.
- Nunca coloque una clave en una página web, extensión de navegador o aplicación móvil. El API no permite solicitudes de navegador (CORS) por esta razón.
- Nunca confirme una clave en git. Si lo hace, revóquela y cree una nueva.
- Use una clave de solo lectura donde solo necesite leer.

## Errores

| Estado | Código               | Por qué                                                                                                                                                                       |
| ------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401    | `unauthorized`       | No hay encabezado `Authorization`, uno mal formado, una clave desconocida o revocada, o un espacio de trabajo de demostración. La respuesta tiene `WWW-Authenticate: Bearer`. |
| 401    | `key_owner_removed`  | La persona que creó la clave ya no tiene acceso al espacio de trabajo. Cree una nueva clave.                                                                                  |
| 403    | `insufficient_scope` | Una clave de solo lectura intentó escribir.                                                                                                                                   |
| 403    | `forbidden`          | La persona que creó la clave no está autorizada a hacer eso (por ejemplo, un Visor no puede escribir).                                                                        |
| 403    | `read_only`          | Las escrituras de API no están disponibles en el plan Free.                                                                                                                   |

Vea [Errores](/docs/api/errors) para la lista completa.

**Las aplicaciones de IA usan un inicio de sesión diferente:** Claude, ChatGPT y otros clientes MCP no usan claves de API. Cada persona se registra con su propio inicio de sesión a través de OAuth. Vea [MCP](/docs/mcp).