Inicio rápido

Siga la Guía de Autenticación para iniciar sesión, luego abra la página de claves de administración y cree una clave de administración. Guárdela por separado de las claves de aplicación estándar. Envíela como token bearer solo a los endpoints de administración de la plataforma.

Una Clave de API estándar no puede llamar a los endpoints de administración de claves ni de guardrails. Una clave de administración válida puede seguir recibiendo 403 Forbidden cuando su propietario ya no tiene el rol de cuenta requerido.

Usa GET /api/v1/keys para inspeccionar las claves visibles para la cuenta de la clave de gestión:

Usa los identificadores públicos devueltos para solicitudes posteriores de recuperación, actualización, revocación o asignación de barreras de seguridad. Nunca inferir el acceso a partir del nombre de una clave o un token enmascarado.

Cree una clave de aplicación con POST /api/v1/keys. El secreto completo se devuelve únicamente en la respuesta de creación, así que guárdelo en su gestor de secretos antes de descartar esa respuesta. La rotación debe crear una clave de reemplazo, desplegarla en la aplicación, verificar el tráfico y luego revocar la clave antigua.

credit_limit_windows acepta cualquier combinación de límites de gasto rotativo 1h, 1d y 7d. Si se agota alguna ventana configurada, las llamadas con esa clave devuelven 429 Too Many Requests hasta que el uso salga de la ventana. Envía un objeto vacío al actualizar una clave para eliminar todos los límites rotativos.

Cuando una solicitud de creación omite todos los campos de límite de gasto y guardrail_id, la nueva clave usa los valores predeterminados de gobernanza del espacio de trabajo. Los límites explícitos, las ventanas móviles o un guardrail sustituyen esa opción predeterminada. Envía credit_limit_cents: null para crear un límite nativo sin restricciones. Un importe proporcionado sin intervalo de restablecimiento sigue siendo un límite de por vida. Las actualizaciones nunca vuelven a aplicar los valores predeterminados del espacio de trabajo, y cambiarlos no modifica las claves existentes.

Crear y actualizar aceptan tags, un array de cadenas key:value completas. Las respuestas de listar, recuperar, crear y actualizar devuelven el array completo. PATCH reemplaza el array; omitir tags lo conserva. La clave debe tener 1–32 caracteres y el valor 1–64, con exactamente un signo de dos puntos y sin espacios en blanco. Se permiten hasta 20 etiquetas distintas, incluidas las predefinidas. Un formato inválido o valores predefinidos en conflicto devuelven 422 con errores de validación; un valor que no sea un array o un elemento que no sea una cadena devuelve 400.

Se exige exactamente una etiqueta de finalidad: usage:developer o usage:service. La creación mediante Management API añade usage:service si no se indica finalidad, incluso con tags: []. La creación en el Dashboard y las actualizaciones sin finalidad usan usage:developer. Las claves existentes se migran como Developer. El entorno es opcional y admite como máximo uno de env:production, env:staging o env:dev (env:prod no se admite).

El panel ofrece accesos rápidos de propósito y entorno al crear o editar, además de etiquetas personalizadas y sugerencias de claves estándar no eliminadas del espacio de trabajo actual. Las listas muestran los valores y la etiqueta completa al pasar el cursor. Las etiquetas no cambian la propiedad, visibilidad ni permisos de las claves. Pueden asociar una clave a un presupuesto compartido por etiqueta.

Los administradores del espacio de trabajo establecen las etiquetas obligatorias de un miembro en Team, mediante el formulario de presupuesto del miembro. Son etiquetas personalizadas que distinguen mayúsculas y minúsculas, como team:growth. Los espacios de nombres usage: y env: están reservados. Un miembro puede tener hasta 19 etiquetas obligatorias y cada clave sigue limitada a 20 etiquetas en total.

Cada nueva clave estándar incluye automáticamente las etiquetas obligatorias de su propietario en ese espacio de trabajo. La creación combina las etiquetas enviadas con las obligatorias antes de validarlas. Por ejemplo, si el miembro requiere team:growth, una solicitud de creación de la Management API con tags: ["project:chatbot"] devuelve project:chatbot, team:growth y el valor predeterminado usage:service.

Un PATCH que incluya tags debe conservar todas las etiquetas obligatorias. Eliminar una devuelve 422 con un error de validación que identifica las etiquetas faltantes, incluso si quien realiza la llamada es administrador. Omitir tags conserva las etiquetas de la clave. Los miembros pueden seguir añadiendo o eliminando etiquetas normales.

Para eliminar una etiqueta obligatoria, un administrador modifica la configuración del miembro en Team. Al guardarla, se añaden las nuevas etiquetas obligatorias a todas las claves estándar existentes de ese miembro y se eliminan las revocadas. Las demás etiquetas no cambian. Esto incluye las claves desactivadas y caducadas, pero excluye las eliminadas. Si alguna clave no admite el conjunto final de etiquetas, falla todo el guardado y el formulario identifica la clave que debe corregirse.

Los presupuestos por etiqueta usan las etiquetas actuales de cada clave. Cambiar las etiquetas obligatorias también cambia la atribución presupuestaria del gasto existente en el período actual. Añadir una etiqueta obligatoria puede agotar su presupuesto inmediatamente. Los miembros existentes comienzan sin etiquetas obligatorias y sus claves no cambian hasta que un administrador guarda una configuración.

Los Guardrails son políticas de cuenta reutilizables para controles de modelo, proveedor y gasto. Administre las políticas a través de /api/v1/guardrails, luego use /api/v1/guardrail_assignments para adjuntarlas o eliminarlas. Trate una asignación rechazada como un error de política o de propiedad en lugar de continuar silenciosamente sin el guardrail.

Cree una protección positiva en modo block y asigne su guardrail_id y una tag que distinga mayúsculas, como dept:ml. Elija exactamente un destino, api_token_id, account_user_id o tag. Los presupuestos por etiqueta requieren un administrador. Los desactivados no aplican límites. Las solicitudes de gestión no consumen presupuesto.

Los presupuestos agrupan las etiquetas actuales de claves estándar, incluido el gasto de claves eliminadas, desactivadas y caducadas. Añadir o quitar una etiqueta mueve el gasto de esa clave del período actual. Crear o recrear un presupuesto nunca reinicia el gasto. El recuento excluye claves eliminadas. Todos los presupuestos coincidentes deben permitir la solicitud; el rechazo devuelve 403 y el nombre de la etiqueta.

Un credit_limit_reset_interval nulo significa un límite vitalicio. Los demás períodos usan UTC. El umbral de alerta predeterminado es 80 y admite de 1 a 100. Las actualizaciones directas afectan a todas las asignaciones; el panel copia primero la política al editar un presupuesto por etiqueta.

La admisión comprueba las reservas. La liquidación puede superarlas, mostrar un uso superior al 100% y bloquear solicitudes de pago posteriores. Los registros usan su fecha de creación; las tareas pendientes y los lotes usan la suya. Una tarea aceptada en un período puede liquidarse en otro posterior.