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

# Autenticación

> Crea una clave de API de espacio de trabajo, envíala como token bearer, acótala con permisos y rótala

Cada solicitud a `/v1` se autentica con una **clave de API de espacio de trabajo**: una credencial de máquina, acotada a un espacio de trabajo y a permisos explícitos.

## Crear una clave

Las claves se crean en la consola, en **Configuración → Claves de API**:

1. Abre tu espacio de trabajo y ve a **Configuración**.
2. En **Claves de API**, elige **Crear clave**, ponle nombre y marca los permisos que necesita.
3. Copia la clave **ahora**: se muestra exactamente una vez y se guarda solo como hash. No se puede recuperar; si la pierdes, crea otra.

Una clave se ve así:

```
wdy_live_x7Qk2m9fB3nP8dR4sT6vW1yZ_a1b2
└──┬─┘ └┬─┘ └──────────┬──────────┘ └─┬─┘
 prefix env      random secret     checksum
```

* **`live` vs `test`** es el segmento de entorno. Usa una clave `test` contra un espacio de trabajo de prueba y una clave `live` en producción; ambas se autentican de la misma forma.
* Los primeros 12 caracteres (`wdy_live_x7Q…`) son el **prefijo** que la consola lista: suficiente para reconocer una clave, nunca suficiente para usarla.

## Envíala

Como token bearer, en cada solicitud:

```bash theme={null}
curl https://api.wondeya.com/v1/me \
  -H "Authorization: Bearer wdy_live_…"
```

`GET /v1/me` es la llamada que debes hacer primero. Devuelve el espacio de trabajo al que pertenece la clave y los permisos que se le otorgaron:

```json theme={null}
{ "workspaceId": "6a1f…", "scopes": ["knowledge:read", "chat:write"] }
```

Cualquier fallo de clave (ausente, malformada, desconocida, revocada o expirada) es el mismo `401` `wondeya.api_key.invalid`, a propósito: distinguirlos sería un oráculo. Una solicitud cuya clave carece de un permiso requerido es un `403` `wondeya.api_key.scope_missing`.

## Permisos (scopes)

A una clave se le otorgan permisos por área y por dirección. Otorga solo lo que una integración necesita.

| Permiso | Otorga |
| - | - |
| `projects:read` / `projects:write` | Sitios: leer, o crear / editar / cambiar de dirección / eliminar |
| `landings:read` / `landings:write` | Agentes y páginas: leer, o crear / editar / publicar / eliminar |
| `knowledge:read` / `knowledge:write` | Fuentes y temas de conocimiento; la recuperación (`/query`) necesita `knowledge:read` |
| `assets:read` / `assets:write` | Imágenes |
| `brand:read` / `brand:write` | La marca del sitio y su menú y pie de página |
| `analytics:read` | Uso (`GET /v1/usage`) |
| `domains:write` | Reservado para los endpoints de dominios propios, que todavía no están disponibles en `/v1`; mientras tanto, administra los dominios en la consola |
| `chat:write` | El turno generativo (`POST /v1/agents/{id}/chat`), que gasta un crédito |

El **tema** de apariencia viaja con `landings:*` (es parte de lo que configura la superficie de páginas). Una clave **sin** permisos se rechaza: «sin permisos» nunca debe leerse como «todos los permisos».

## Rotar

Un espacio de trabajo mantiene a lo sumo **dos claves activas** a la vez, así que una rotación tiene una ventana de superposición:

1. Crea una segunda clave con los mismos permisos.
2. Despliégala en todos los lugares donde se usaba la anterior.
3. Revoca la primera clave en la consola.

Revocar es inmediato. No existe «regenerar»: una clave rotada es una clave nueva, y el secreto anterior desaparece en el momento en que se revoca.


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