API de claves de API #

Estos endpoints le permiten gestionar las claves de API de su cuenta desde el código. Todos ellos operan únicamente sobre las claves de la propia cuenta que realiza la llamada.

Existen dos tipos de claves y residen en rutas diferentes:

• Su clave principal: la única clave de acceso completo que se encuentra en Configuración → Integraciones → Clave de API. Consulte su vista previa enmascarada, verifique el uso de su límite de tasa, rótela o revóquela. Estos son los endpoints /api-keys/current, /api-keys/rotate y /api-keys/usage a continuación.
• Claves con ámbito (Scoped keys): claves adicionales con nombre que usted crea para una tarea específica, cada una limitada a las partes de la API que usted elija. Estos son los endpoints /api-keys y /api-keys/{id} bajo Claves con ámbito. Nada cambia en su clave principal cuando crea una; las integraciones existentes continúan sin verse afectadas.

Todas las rutas a continuación son relativas a la URL base de la API:

https://api.youraiconnector.com/v1

Cada solicitud debe estar autenticada. Consulte Autenticación para conocer los cuatro métodos aceptados. Los ejemplos aquí utilizan el encabezado X-API-Key (y una forma de parámetro de consulta para cURL).

Lea esto primero. La rotación o revocación de su clave surte efecto inmediatamente. En el momento en que cualquiera de las llamadas tiene éxito, la clave anterior deja de funcionar; cada integración que aún la utilice comenzará a recibir errores 401. Planifíquelo: rote la clave durante una ventana de mantenimiento y actualice todas sus integraciones de inmediato.

Obtener metadatos de la clave actual #

Devuelve su clave activa: la clave completa en api_key cuando existe una copia recuperable, una vista previa enmascarada (los primeros 4 y los últimos 4 caracteres) y, cuando está disponible, la fecha en que se creó. api_key es null para las claves creadas antes de que se guardaran copias recuperables; rótela una vez y la nueva clave podrá mostrarse de nuevo más tarde.

GET /api-keys/current

cURL

curl "https://api.youraiconnector.com/v1/api-keys/current?apiKey=YOUR_API_KEY"

JavaScript

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

Python

import requests

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

Respuesta

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "api_key_masked": "abcd...qrst",
  "created_at": "2026-06-01T10:00:00.000Z"
}

Si la cuenta no tiene una clave de API, la respuesta es 404 con { "success": false, "error": "No API key found for this account" }.

Obtener el uso del límite de tasa #

Devuelve el uso de su límite de tasa para la ventana actual: el límite de solicitudes por ventana, cuántas solicitudes se han contabilizado hasta el momento, cuántas quedan y cuándo se restablece la ventana. Utilice esto para crear una limitación (throttling) del lado del cliente, de modo que su integración reduzca la carga antes de alcanzar las respuestas 429.

GET /api-keys/usage

cURL

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

JavaScript

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

Python

import requests

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

Respuesta

{
  "success": true,
  "usage": {
    "limit": 300,
    "window_seconds": 60,
    "used": 37,
    "remaining": 263,
    "window_resets_at": "2026-06-09T12:01:00.000Z"
  }
}

Si aún no se han registrado solicitudes en la ventana actual, el uso se informa como cero y la respuesta incluye un campo note que explica el motivo.

Rotar la clave #

Genera una nueva clave de API e invalida la anterior en el mismo paso. Utilice esto si sospecha que su clave se ha filtrado, o como parte de una política regular de rotación de credenciales.

POST /api-keys/rotate

La nueva clave se muestra una sola vez. Se devuelve en esta respuesta y no se puede recuperar por completo después; guárdela de forma segura en el momento en que la reciba. La clave anterior deja de funcionar en el instante en que esta llamada tiene éxito, así que actualice todas las integraciones que la utilizaban.

cURL

curl -X POST "https://api.youraiconnector.com/v1/api-keys/rotate?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys/rotate", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys/rotate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.

Respuesta

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "message": "API key rotated. The previous key is no longer valid. Store this key now — it will not be shown again."
}

Revocar la clave #

Elimina permanentemente la clave de API de su cuenta. La revocación es inmediata: cada solicitud posterior que utilice la clave revocada (incluidas integraciones como Make, Zapier o scripts personalizados) será rechazada con un 401. Para restaurar el acceso a la API después, genere una nueva clave desde la configuración de su cuenta mientras haya iniciado sesión en la aplicación.

DELETE /api-keys/current

No se puede deshacer. A diferencia de la rotación, la revocación no le proporciona una clave de reemplazo. Solo revoque cuando tenga la intención de detener el acceso a la API (por ejemplo, una clave filtrada que no puede reemplazar de inmediato).

cURL

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

JavaScript

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

Python

import requests

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

Respuesta

{
  "success": true,
  "revoked": true,
  "message": "API key revoked. All requests using it will be rejected immediately."
}

Si la cuenta no tiene ninguna clave que revocar, la respuesta es 404.

Claves con ámbito #

Una clave con ámbito es una clave de API adicional que usted crea para una tarea específica, con solo el acceso que esa tarea necesita. El caso clásico: desea conectar un panel de cliente, una herramienta de informes o un script interno a su cuenta sin entregar una clave que también pueda enviar mensajes, cambiar sus agentes de IA o comprar un número de teléfono.

La restricción acompaña a la clave misma, por lo que quien la posea solo puede hacer lo que usted permitió cuando la creó.

Qué puede restringir

También puede darle a una clave una fecha de expires_at (ISO 8601, y debe ser en el futuro). Después de ese momento, la clave deja de funcionar por sí sola. Si la omite, la clave nunca caducará hasta que usted la revoque.

Las denegaciones se cierran por defecto. Si una solicitud cae fuera de lo que la clave permite, se rechaza en lugar de permitirse: una escritura con una clave de solo lectura devuelve 403 con error_code: "key_read_only", y cualquier cosa fuera de las secciones permitidas de la clave devuelve 403 con error_code: "key_scope_denied". Si una clave con ámbito recibe un 403 inesperado, el endpoint al que llamó simplemente no está dentro de sus ámbitos: amplíe la clave o use su clave principal.

Solo el propietario de la cuenta gestiona las claves. Estos cuatro endpoints requieren su clave principal o una sesión de propietario en la aplicación. Una clave con ámbito nunca puede listar, crear, editar o revocar claves (incluida ella misma), por lo que una clave restringida nunca puede usarse para crear una más amplia. Intentarlo devuelve 403 con error_code: "key_scope_denied". Por la misma razón, API Keys no es una sección que pueda conceder: solicitarla devuelve 400 con error_code: "invalid_scopes".

Listar claves con ámbito #

Devuelve las claves con ámbito de la cuenta, de la más nueva a la más antigua (hasta 200), incluidas las revocadas para que pueda ver qué se retiró y cuándo. Solo se devuelven vistas previas enmascaradas: el valor de una clave con ámbito se muestra una vez, en el momento de la creación, y nunca se puede recuperar después.

GET /api-keys

cURL

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

Respuesta

{
  "success": true,
  "api_keys": [
    {
      "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
      "label": "Client dashboard - Acme",
      "key_preview": "abcd...qrst",
      "scopes": {
        "read_only": true,
        "tags": ["Analytics"],
        "sub_account_ids": [],
        "rate_limit_per_min": 60
      },
      "expires_at": null,
      "last_used_at": "2026-08-20T14:03:00.000Z",
      "created_at": "2026-08-14T09:12:00.000Z",
      "revoked_at": null,
      "revoked": false
    }
  ]
}

Crear una clave con ámbito #

Crea una nueva clave con ámbito y devuelve su valor una sola vez.

POST /api-keys

La clave se muestra una sola vez. Aparece en esta respuesta y en ningún otro lugar, nunca; no hay forma de consultarla de nuevo posteriormente. Guárdela en el momento en que la reciba. Si la pierde, revóquela y cree otra.

Campos del cuerpo — todos opcionales:

cURL

curl -X POST "https://api.youraiconnector.com/v1/api-keys" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    }
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    label: "Client dashboard - Acme",
    scopes: { read_only: true, tags: ["Analytics"] },
  }),
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "label": "Client dashboard - Acme",
        "scopes": {"read_only": True, "tags": ["Analytics"]},
    },
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.

Respuesta — 201 Created

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    },
    "expires_at": null,
    "revoked": false
  },
  "message": "Store this key now — it is shown once and cannot be retrieved again."
}

Un par de detalles que vale la pena conocer al desarrollar con esto:

• Omitir scopes no es lo mismo que enviar una lista tags vacía. Si deja scopes fuera por completo, obtendrá el valor predeterminado seguro (solo lectura, solo Analytics). Si envía "tags": [] a propósito, la clave podrá usar todas las secciones; esto se interpreta como una solicitud deliberada de una clave sin restricciones.
• read_only permanece como true a menos que envíe explícitamente false. Un error tipográfico o una marca faltante nunca pueden producir accidentalmente una clave que pueda escribir.

Actualizar una clave con ámbito #

Cambia la etiqueta, los ámbitos y/o la caducidad de una clave. Envíe cualquier combinación de los tres; si no envía ninguno, se devolverá 400.

PATCH /api-keys/{id}

El {id} es el id de la clave de la lista (el valor key_...), nunca la clave en sí.

Los ámbitos se reemplazan, no se combinan. Lo que envíe se convierte en el conjunto completo de permisos de la clave. Esto es deliberado: restringir una clave nunca puede dejar silenciosamente el acceso anterior y más amplio en su lugar. Envíe siempre el objeto scopes completo que desea, no solo el campo que está cambiando.

El valor de la clave nunca cambia. No existe la rotación in situ para una clave con ámbito; para renovarla, cree una clave nueva y revoque la anterior, de modo que el acceso de una credencial nunca pueda cambiar mientras una integración la siga utilizando.

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme (read-only)",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    }
  }'

Respuesta

{
  "success": true,
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme (read-only)",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    },
    "expires_at": null,
    "last_used_at": "2026-08-20T14:03:00.000Z",
    "created_at": "2026-08-14T09:12:00.000Z",
    "revoked_at": null,
    "revoked": false
  }
}

Si no hay ninguna clave con ese id en su cuenta, la respuesta es 404.

Revocar una clave con ámbito #

La revocación es inmediata: la siguiente solicitud que utilice esa clave será rechazada con un 401. Su clave principal y cualquier otra clave con ámbito no se verán afectadas.

DELETE /api-keys/{id}

La clave permanece en su lista marcada como "revoked": true, por lo que conserva el registro de lo que existía y a qué podía acceder. Revocar una clave que ya está revocada se realiza correctamente y no cambia nada.

cURL

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

Respuesta

{
  "success": true,
  "revoked": true,
  "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
  "message": "API key revoked. All requests using it will be rejected immediately."
}

Errores de la API de claves de API #

Los endpoints de claves de API devuelven el sobre de error estándar:

{
  "success": false,
  "error": "No API key found for this account"
}

En un endpoint de clave de API, una clave faltante o no válida devuelve 401 y una cuenta sin clave registrada devuelve 404. Los códigos compartidos que puede devolver cualquier endpoint — 400, 403 (su plan no incluye acceso a la API), 429 (límite de tasa) y 500 — se enumeran con orientación sobre reintentos en Errores y paginación.

Los endpoints de claves con ámbito añaden algunos códigos con nombre en el campo error_code para que pueda distinguir los casos:

Próximos pasos #

• Autenticación — las cuatro formas de autenticar una solicitud y cómo se aplican los ámbitos de las claves.
• Errores y límites de tasa — códigos de estado y el límite de 300 peticiones/min.