Claves de provisioning

Una clave de provisioning permite a su backend crear y gestionar claves de API de inferencia de forma programática — sin que nadie inicie sesión en la Consola. Ideal para productos SaaS que emiten una clave por cliente final, por dispositivo o por job de CI.

Cómo funciona

1. Un owner o admin crea una clave de provisioning en Consola → Claves de provisioning. Lleva el prefijo sk-syn-prov-.
2. Su backend llama a los /api/provisioning/* endpoints con esa clave para crear claves de inferencia (prefijo sk-syn-).
3. Cada clave de inferencia está limitada al mismo workspace y puede llevar un límite de gasto en USD y metadata opacos.
4. Entregue las claves de inferencia a sus clientes. Revoque cualquiera de ellas individualmente en cualquier momento — eliminar una clave de provisioning no afecta a las claves de inferencia que ya creó.

Autenticación

Pase la clave de provisioning como Bearer token. Funciona solo en /api/provisioning/* — una clave de provisioning no puede realizar llamadas de inferencia, y una clave de inferencia normal no puede llamar a estos endpoints de gestión (ambas devuelven 401 wrong_key_kind).

Authorization: Bearer sk-syn-prov-...

Crear una clave de inferencia

POST /api/provisioning/keys

curl https://synthorai.io/api/provisioning/keys \
  -H "Authorization: Bearer sk-syn-prov-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Device abc-123",
    "quota": 5.0,
    "allowed_models": "claude-haiku-4-5",
    "metadata": { "tenant_id": "acme", "device_id": "abc-123" }
  }'

import requests

resp = requests.post(
    "https://synthorai.io/api/provisioning/keys",
    headers={"Authorization": "Bearer sk-syn-prov-..."},
    json={
        "name": "Device abc-123",
        "quota": 5.0,
        "allowed_models": "claude-haiku-4-5",
        "metadata": {"tenant_id": "acme", "device_id": "abc-123"},
    },
)
inference_key = resp.json()["key"]  # full key — shown only once

La respuesta devuelve la clave completa en el key campo exactamente una vez. Guárdela de inmediato — no se puede recuperar más tarde.

{
  "id": 42,
  "key": "sk-syn-d4f0...e91b",
  "key_prefix": "sk-syn-d4f0...",
  "name": "Device abc-123",
  "kind": "inference",
  "created_via": "provisioning_api",
  "parent_provisioning_id": 7,
  "workspace_id": 11,
  "quota_usd": 5.0,
  "unlimited_quota": false,
  "allowed_models": "claude-haiku-4-5",
  "metadata": { "tenant_id": "acme", "device_id": "abc-123" },
  "created_at": "2026-06-01T12:00:00Z"
}

Listar claves de inferencia

GET /api/provisioning/keys

Lista todas las claves de inferencia del workspace. Filtre por cualquier campo de metadatos con ?metadata.<key>=<value>; varios filtros se combinan con AND.

# all keys
curl https://synthorai.io/api/provisioning/keys \
  -H "Authorization: Bearer sk-syn-prov-..."

# only keys tagged tenant_id=acme
curl "https://synthorai.io/api/provisioning/keys?metadata.tenant_id=acme" \
  -H "Authorization: Bearer sk-syn-prov-..."

Recuperar, actualizar y eliminar

Direccione una sola clave de inferencia por su id:

• GET /api/provisioning/keys/{id} — obtener una clave.
• PATCH /api/provisioning/keys/{id} — actualizar name, quota, status, allowed_models, ip_whitelist, expires_at, include_byok_in_limit, o metadata. Los campos kind y de linaje no se pueden cambiar.
• DELETE /api/provisioning/keys/{id} — revocar una clave. Efecto inmediato.

# disable a key (status 2 = disabled)
curl -X PATCH https://synthorai.io/api/provisioning/keys/42 \
  -H "Authorization: Bearer sk-syn-prov-..." \
  -H "Content-Type: application/json" \
  -d '{ "status": 2 }'

# delete a key
curl -X DELETE https://synthorai.io/api/provisioning/keys/42 \
  -H "Authorization: Bearer sk-syn-prov-..."

Cuotas y control de gasto

quota es un límite en USD por clave de inferencia. El uso se mide después de cada solicitud, por lo que una clave puede superar ligeramente su límite dentro de una breve ventana de liquidación bajo alta concurrencia — dimensione los límites con un pequeño margen para modelos de alto valor. Lea el gasto actual de una clave desde used_usd en las respuestas de listado / recuperación.

¿Estás dimensionando límites en USD por clave? La LLM API cost calculator convierte el volumen de tokens previsto de un cliente en un gasto mensual que puedes fijar como quota.