Autenticación

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:

Abre tu espacio de trabajo y ve a Configuración.
En Claves de API, elige Crear clave, ponle nombre y marca los permisos que necesita.
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:

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:

{ "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:

Crea una segunda clave con los mismos permisos.
Despliégala en todos los lugares donde se usaba la anterior.
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.

Resumen

Endpoints

Crear una clave

Envíala

Permisos (scopes)

Rotar

​Crear una clave

​Envíala

​Permisos (scopes)

​Rotar

Crear una clave

Envíala

Permisos (scopes)

Rotar