Claves de administración

Con una clave de administración gestionas un espacio de trabajo desde tu propio código. Crea y limita las claves de inferencia que usan tus clientes o dispositivos, y lee el uso, los registros y la configuración. No puede llamar a ningún modelo.

Crear una clave de administración

1. En la consola, abre Claves API › Claves de administración y elige Crear clave de administración. Pueden hacerlo los administradores y el propietario del espacio de trabajo.
2. Elige a quién pertenece la clave y qué ámbitos tiene.
3. Copia la clave. Empieza por sk-syn-admin- y solo se muestra una vez.

Ámbitos

Cada ámbito da acceso a una parte de la API de gestión. Un ámbito de escritura incluye el de lectura correspondiente. Si la clave no tiene el ámbito que pide una solicitud, la respuesta es 403 insufficient_scope.

A quién pertenece una clave

• A ti. La clave se desactiva si sales del espacio de trabajo. Si sigues en él pero dejas de ser administrador, las solicitudes devuelven 403 key_creator_not_authorized.
• Al espacio de trabajo. La clave sigue funcionando aunque quien la creó se vaya o cambie de rol. Úsala para CI e integraciones. Si quien la creó se va, la clave pasa al propietario del espacio de trabajo junto con las claves de inferencia que creó, y todas siguen funcionando.

Lo eliges al crear la clave. Después no se puede cambiar.

Autenticación

Envía la clave como token Bearer. Una clave de administración solo sirve en la API de gestión: los endpoints de modelos bajo /v1/ la rechazan, y la API de gestión rechaza una clave de inferencia (sk-syn-) con 401 wrong_key_kind.

Authorization: Bearer sk-syn-admin-...

Crear una clave de inferencia

POST /api/v1/keys

curl https://synthorai.io/api/v1/keys \
  -H "Authorization: Bearer sk-syn-admin-..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: device-abc-123" \
  -d '{
    "name": "Device abc-123",
    "limit_usd": 5.0,
    "limit_reset": "monthly",
    "allowed_models": ["claude-haiku-4-5"],
    "metadata": { "tenant_id": "acme", "device_id": "abc-123" }
  }'

import requests

resp = requests.post(
    "https://synthorai.io/api/v1/keys",
    headers={
        "Authorization": "Bearer sk-syn-admin-...",
        "Idempotency-Key": "device-abc-123",
    },
    json={
        "name": "Device abc-123",
        "limit_usd": 5.0,
        "limit_reset": "monthly",
        "allowed_models": ["claude-haiku-4-5"],
        "metadata": {"tenant_id": "acme", "device_id": "abc-123"},
    },
)
inference_key = resp.json()["data"]["key"]  # full key - shown only once

La respuesta incluye la clave completa en key, una sola vez. Guárdala en ese momento: las lecturas posteriores solo devuelven key_prefix.

{
  "data": {
    "id": 42,
    "key": "sk-syn-d4f0...e91b",
    "key_prefix": "sk-syn-d4f0...",
    "name": "Device abc-123",
    "enabled": true,
    "status": "enabled",
    "limit_usd": 5.0,
    "used_usd": 0,
    "limit_reset": "monthly",
    "allowed_models": ["claude-haiku-4-5"],
    "ip_allowlist": [],
    "expires_at": null,
    "include_byok_in_limit": true,
    "rate_limit": { "rpm": 0, "tpm": 0 },
    "metadata": { "tenant_id": "acme", "device_id": "abc-123" },
    "created_via": "provisioning_api",
    "created_at": "2026-10-01T12:00:00Z"
  },
  "meta": { "request_id": "01a1..." }
}

Para reintentar una creación sin riesgo, envía una cabecera Idempotency-Key. Si repites la solicitud con el mismo valor, recibes la primera respuesta, sin el secreto. La clave devuelve esa respuesta durante 24 horas, aunque el recurso se haya eliminado entretanto: para volver a crearlo, usa una clave nueva.

Listar y filtrar claves

GET /api/v1/keys

Filtra por cualquier campo de los metadatos con ?metadata.<name>=<value>. Los resultados llegan paginados: pasa meta.next_cursor como cursor para obtener la página siguiente.

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

# only keys tagged tenant_id=acme, 50 at a time
curl "https://synthorai.io/api/v1/keys?metadata.tenant_id=acme&limit=50" \
  -H "Authorization: Bearer sk-syn-admin-..."

Leer, cambiar, rotar y eliminar

• GET /api/v1/keys/{id} devuelve una clave.
• PATCH /api/v1/keys/{id} cambia solo los campos que envíes. "enabled": false detiene la clave sin eliminarla.
• POST /api/v1/keys/{id}/rotate da a la clave un secreto nuevo. El anterior deja de funcionar al instante.
• DELETE /api/v1/keys/{id} elimina la clave. Las solicitudes que la usen devuelven 401 al instante.

# stop a key without deleting it
curl -X PATCH https://synthorai.io/api/v1/keys/42 \
  -H "Authorization: Bearer sk-syn-admin-..." \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

# give it a new secret
curl -X POST https://synthorai.io/api/v1/keys/42/rotate \
  -H "Authorization: Bearer sk-syn-admin-..."

# delete it
curl -X DELETE https://synthorai.io/api/v1/keys/42 \
  -H "Authorization: Bearer sk-syn-admin-..."

Una clave de administración actúa en nombre de un solo miembro: quien la creó o, si la clave es del espacio de trabajo y quien la creó se ha ido, el propietario. Solo puede cambiar, rotar y eliminar las claves de ese miembro, incluidas las que creó ella misma; con la clave de otro miembro, la respuesta es 403 not_key_creator, aunque uses la clave de administración del propietario. En una instancia dedicada, cualquier clave de administración del espacio de trabajo puede gestionar las claves de todos los miembros, igual que los administradores en la consola. Si un administrador desactivó una clave, solo un administrador puede volver a activarla; cualquier otra persona recibe 403 disabled_by_admin.

Límites y gasto

limit_usd es lo que la clave puede gastar y used_usd, lo que lleva gastado. Al llegar al límite, status pasa a limit_reached y las solicitudes se rechazan hasta que subas el límite o se reinicie el periodo.

¿Tienes que calcular el límite de gasto de cada clave? La calculadora de costes de API de LLM convierte el volumen de tokens que esperas de un cliente en una cifra mensual que puedes poner en limit_usd.

Errores

Los errores llegan en el formato de la API de gestión: error.code indica el motivo y error.message, qué hacer. En /api/provisioning/keys, el mismo código llega en error.type. Estos son los códigos propios de las claves de administración y de los endpoints de claves:

Claves de aprovisionamiento y /api/provisioning

Las claves emitidas antes de que existieran las claves de administración (sk-syn-prov-) siguen funcionando, con los ámbitos keys.read y keys.write. La dirección anterior, /api/provisioning/keys, sigue disponible con sus propios nombres de campo (quota, status). Para integraciones nuevas, usa /api/v1/keys.

La API de gestión cubre también la facturación, el registro de solicitudes, los prompts y la configuración del espacio de trabajo. Consulta la descripción general de la API y el documento OpenAPI.