Your AI Connector Docs

Autenticación

Cada solicitud a la API debe incluir su clave de API para que Your AI Connector sepa quién es usted y sobre qué cuenta debe actuar. Puede enviar la clave de cuatro formas diferentes; todas funcionan en cualquier endpoint que acepte autenticación mediante clave de API, así que elija la que mejor se adapte a su configuración.

El acceso a la API es una función de pago. Si su plan no la incluye, las solicitudes serán rechazadas con un 403 incluso cuando la clave sea válida; consulte La restricción de funciones de pago a continuación. Para generar una clave, consulte Acceso a la API.

Solo HTTPS. Todas las solicitudes deben utilizar una conexión segura. Las solicitudes HTTP simples son rechazadas antes incluso de que se ejecute la autenticación.

Resumen de los cuatro métodos

Método Transportador Cuándo usarlo
Parámetro de consulta ?apiKey=YOUR_API_KEY Pruebas rápidas y URLs de navegador
Cabecera X-API-Key: YOUR_API_KEY Integraciones en producción
Cabecera Bearer Authorization: Bearer YOUR_API_KEY Integraciones en producción
Token de ID de Firebase Authorization: Bearer <ID token> Solo sesiones de aplicaciones propias

Cuando hay más de uno presente, el parámetro de consulta tiene prioridad, seguido de la cabecera X-API-Key y, finalmente, el token bearer. En la práctica, solo se envía uno.

1. Parámetro de consulta — ?apiKey=

Añada su clave al final de la dirección web. Esta es la forma más sencilla y siempre funciona, lo que la hace ideal para pruebas rápidas, scripts y cualquier herramienta antigua.

cURL

curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY");
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    params={"apiKey": "YOUR_API_KEY"},
)
data = res.json()

Aviso: Las direcciones web quedan registradas en el historial del navegador, en los registros de acceso del servidor y en los registros de proxy. Para cualquier cosa que no sea una prueba rápida, prefiera uno de los métodos de cabecera a continuación para que su clave no se escriba en el disco a plena vista.

2. Cabecera X-API-Key

Envíe la clave en una cabecera dedicada. Esto la mantiene fuera de la URL y es la opción recomendada para producción.

cURL

curl "https://api.youraiconnector.com/v1/contacts" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

3. Encabezado Authorization: Bearer

También puede pasar la clave como un token de portador (bearer token) estándar. Esto es útil cuando su cliente o framework HTTP ya tiene soporte integrado para encabezados Authorization.

cURL

curl "https://api.youraiconnector.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = res.json()

La API distingue automáticamente su clave de API de un token de inicio de sesión, por lo que este método funciona exactamente igual que X-API-Key.

4. Token de ID de Firebase (solo para aplicaciones de primera parte)

Si está creando una aplicación de primera parte que inicia sesión a los usuarios a través del propio inicio de sesión de Your AI Connector, puede pasar el token de ID de Firebase del usuario que ha iniciado sesión como un token de portador en lugar de una clave de API:

Authorization: Bearer <Firebase ID token>

El token se verifica en cada solicitud y se asigna a la cuenta que ha iniciado sesión. Este método es solo para sesiones de aplicaciones de primera parte: no puede crear estos tokens desde una integración externa y no hay forma de obtener uno sin pasar por el inicio de sesión normal de la aplicación. Para integraciones de servidor a servidor y de terceros, utilice una clave de API (métodos 1–3).

Cuándo usar cada uno

  • Pruebas rápidas y scripts únicos → parámetro de consulta (?apiKey=). Es lo más rápido de escribir y funciona en un navegador.
  • Integraciones de producción y llamadas de servidor a servidor → X-API-Key o Authorization: Bearer YOUR_API_KEY. Mantiene la clave fuera de las URL y los registros.
  • Aplicaciones de primera parte con un usuario de Your AI Connector que ha iniciado sesión → Authorization: Bearer <Firebase ID token>.

Alcances de las claves

Su cuenta tiene una clave de API principal: la que se encuentra en Configuración → Integraciones → Clave de API. Tiene acceso completo a todo lo que la cuenta puede hacer.

También puede crear claves con alcance limitado: claves con nombre que solo acceden a las partes de la API que usted elija, por ejemplo, una clave de solo lectura limitada a Analytics para un panel de informes. Una clave con alcance limitado se envía exactamente igual que la clave principal (cualquiera de los métodos 1–3 anteriores), pero se verifica con sus propios permisos en cada solicitud:

  • Fuera de sus áreas permitidas, se rechaza. Una escritura con una clave de solo lectura, o una llamada a una sección para la que no se otorgó la clave, devuelve un 403 — key_read_only o key_scope_denied en el campo error_code. La verificación es deliberadamente estricta: todo lo que no esté claramente dentro de las áreas permitidas de la clave se rechaza en lugar de permitirse, por lo que si ve uno de esos 403, la clave simplemente no cubre ese endpoint.
  • Tiene su propio presupuesto de límite de tasa. Una clave con alcance limitado se cuenta por separado de su clave principal, por lo que un panel de control ocupado que utilice una clave con alcance limitado no puede agotar la asignación de la que dependen sus otras integraciones. Usted elige ese presupuesto por minuto cuando crea la clave.
  • No puede administrar claves de API. Solo el propietario de la cuenta (iniciando sesión o utilizando la clave principal) puede listar, crear, editar, rotar o revocar claves. Una clave con alcance limitado nunca puede crear una clave con mayor alcance.

Consulte Claves de API para saber cómo crear, editar y revocar claves con alcance limitado.

El control de funciones de pago

El acceso a la API es una función de pago. Cuando su plan no lo incluye, una solicitud con una clave válida se rechaza con 403:

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

If you see this, check your plan or contact hi@youraiconnector.com. A missing or wrong key returns 401 instead:

{
  "success": false,
  "error_code": 401,
  "error": "Invalid API key"
}

Mantenga su clave segura

  • Trate la clave como una contraseña. Su clave principal otorga acceso completo a su cuenta. Si necesita entregar una clave a una herramienta o a una persona que solo necesita una parte de ella, cree una clave con alcance limitado; consulte Alcances de las claves.
  • Manténgala en el lado del servidor. Nunca la incruste en JavaScript de navegador, en un paquete de aplicación móvil o en cualquier código que un usuario final pueda leer.
  • Almacénela en un administrador de secretos o en la configuración del lado del servidor, no en el control de código fuente.
  • Rótela si se filtra. Genere una nueva clave desde el panel de control o llame a POST https://api.youraiconnector.com/v1/api-keys/rotate; esto invalida inmediatamente la anterior. Consulte Claves de API.
  • Utilice siempre HTTPS para que la clave esté cifrada durante el tránsito.

Próximos pasos