Autenticación

Cada solicitud a la API de Sursa lleva una clave de API, o un token de acceso OAuth de una aplicación, en el encabezado Authorization:

Authorization: Bearer kb_3f9c…

La clave identifica a la organización y decide qué puede ver y cambiar la solicitud: su rol, sus ámbitos, su perfil de datos y sus colecciones. En la dirección de la API no hay sesiones ni cookies. Cada solicitud se autentica por separado, así que puede enviar solicitudes en paralelo y desde varios servidores con la misma clave.

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"

Las integraciones anteriores pueden enviar la clave en un encabezado X-API-Key. Se sigue aceptando, pero el código nuevo debe usar Authorization: Bearer.

Tipos de credenciales

Credencial	Aspecto	Dónde funciona
Clave de API de la organización	`kb_…`	En todos los endpoints de la API, dentro de su rol, sus ámbitos, su perfil de datos y sus colecciones.
Clave de una fuente personalizada	`kbsrc_…`	Solo en los endpoints de envío de su propia fuente personalizada (`/v1/push/sources/{source_id}/…`).
Token de acceso OAuth	`kbat_…`	En los endpoints de la referencia de la API, dentro de los ámbitos del token. Un token de `POST /oauth/token` obtenido con un código de autorización actúa en nombre del empleado que dio su consentimiento; un token `client_credentials` actúa en nombre de la organización, como una clave de API. Es válido durante 1 hora.

Todas se envían de la misma manera. Una clave de fuente personalizada no puede leer, buscar ni cambiar nada fuera de su fuente; úsela donde la clave la guarde un tercero, por ejemplo una plataforma de integración.

Errores de autenticación

Estado y código	Qué significa	Qué hacer
`401` `auth.not_authenticated`	No hay clave, la clave está mal escrita o se ha revocado.	Compruebe el encabezado y el valor de la clave.
`401` `api_keys.expired`	La clave ha superado su fecha de caducidad.	Cree una clave nueva y sustituya la anterior.
`401` `sources.push_key_invalid`	La clave de la fuente personalizada es incorrecta, se ha revocado o pertenece a otra fuente.	Compruebe la clave y el ID de la fuente en la ruta.
`401` `oauth.token_expired`	El token de acceso OAuth ha caducado.	Obtenga uno nuevo con el token de actualización.
`403` `api_keys.scope`	La clave no tiene el ámbito necesario para esta operación.	Añada el ámbito o use una clave que lo tenga.
`403` `api_keys.feature_disabled`	El plan de la organización no incluye claves de API.	Póngase en contacto con el administrador de la organización.
`403` `api_keys.ip_not_allowed`	La solicitud procede de una dirección que no está entre las direcciones permitidas de la clave.	Llame desde una red permitida o cambie las direcciones de la clave.
`403` `api_keys.mcp_only`	Se usó una clave MCP personal fuera del endpoint `/mcp`.	Use una clave de API de la organización para la API.
`403` `oauth.operation_not_allowed`	La operación no forma parte de la API pública, así que un token OAuth no puede llamarla.	Use una operación de la referencia de la API.
`403` `org.suspended`	La organización está suspendida. Sus datos se conservan.	Póngase en contacto con el administrador de la organización.

403 significa que la solicitud se autenticó, pero no está permitida. Un objeto que la clave no puede ver responde 404, igual que un objeto que no existe, de modo que una clave no puede averiguar qué hay fuera de su acceso.

Actuar como un perfil de datos

Una clave con el rol admin puede comprobar qué vería otro grupo de personas: el encabezado X-View-As ejecuta una solicitud como un perfil de datos y, si se desea, con un rol.

curl "https://api.sursa.com/v1/cards?limit=20" \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "X-View-As: employee:viewer"

Las solicitudes en este modo solo leen: cualquier cambio devuelve 403 con el código view_as.read_only. Un token OAuth, o una clave sin el rol admin, no puede usar X-View-As: la solicitud responde 403 con el código view_as.admin_key_required. Un encabezado que no nombra ningún perfil existente responde 400 con el código view_as.invalid_header.

Aplicaciones de navegador

La API admite solicitudes desde cualquier origen web (Access-Control-Allow-Origin: *) y nunca usa cookies, así que una página puede llamarla con fetch. En ese caso, la clave queda en la página y la ve cualquiera que la use. Llame a la API desde el navegador solo con una clave que esté dispuesto a mostrar a esos usuarios, como una clave viewer limitada a colecciones públicas, o ponga su propio servidor entre el navegador y Sursa.

Lo que solo puede hacer un empleado

Una clave de API de la organización actúa en nombre de la organización, no de una persona. Dos partes de la API pertenecen a las personas, así que solo funcionan con un token que actúa en nombre de un empleado: una sesión en Sursa o un token de acceso OAuth emitido con el consentimiento del empleado.

Las conversaciones pertenecen a una persona. Una clave de API de la organización solo ve en GET /v1/conversations las conversaciones que inició ella misma. La API pública no tiene ninguna operación que inicie una conversación, así que para una clave la lista suele estar vacía, y las conversaciones de los empleados nunca se le muestran. Las preguntas sin conversación, con POST /v1/ask o POST /v1/chat, funcionan con cualquier clave que tenga el ámbito ask. Para listar las conversaciones de un empleado y leer el historial de una de ellas con GET /v1/conversations/{conv_id}, llame a la API con un token OAuth en nombre de ese empleado. El token solo ve las conversaciones del propio empleado; cualquier otra conversación responde 404 con el código conversations.not_found.

Solo un empleado verifica una tarjeta. La verificación confirma que una persona revisó el contenido, por eso POST /v1/cards/{card_id}/verification/verify y POST /v1/cards/{card_id}/verify requieren una sesión o un token OAuth en nombre de un empleado que pueda verificar la tarjeta. Con una clave de API de la organización, o con un token client_credentials, responden 400 con el código cards.verify_user_account_required. Las comprobaciones habituales van primero: una tarjeta que la clave no puede ver responde 404, y si la clave no tiene permiso para verificarla, la respuesta es 403.