Machine keys

Una machine key es una credencial no-humana con un scope explícito y revocable. Es lo que tu agente usa para autenticarse contra el plano de control. No es tu API key personal.

Por qué importa la diferencia

Si pegás tu credencial humana a tu agente, tres cosas malas:

1. Si comprometen al agente, comprometen tu cuenta entera.
2. No podés saber qué hizo el agente vs qué hiciste vos en el audit log.
3. Si rotás tu password (o tu sesión expira), el agente deja de funcionar.

Con machine key:

• El scope es limitado (workspace:read solo, workspace:admin controlado, etc.).
• Audit log marca cada acción con actor=key:<id> — sabés qué fue automatizado.
• Rotación es independiente de tu sesión humana.
• Revocación es un click cuando algo va mal.

Crear una machine key

Vía dashboard (recomendado primera vez): app.prysmid.com → settings → machine keys → New. Elegís nombre, scope, expiración (o “no expira”). Descargás el JSON. No se vuelve a mostrar — si lo perdés, generás una nueva.

Vía API:

curl -X POST https://api.prysmid.com/v1/workspaces/$WS/machine-keys \
  -H "Authorization: Bearer $YOUR_HUMAN_TOKEN" \
  -d '{
    "name": "claude-desktop-fernando",
    "scopes": ["workspace:admin"],
    "expires_at": "2027-04-28T00:00:00Z"
  }'

Response (la única vez que se muestra el secret):

{
  "id": "mk_abc123",
  "name": "claude-desktop-fernando",
  "scopes": ["workspace:admin"],
  "expires_at": "2027-04-28T00:00:00Z",
  "created_at": "2026-04-28T10:00:00Z",
  "key": {
    "type": "service_account",
    "key_id": "192038...",
    "key_secret": "<long PEM-style string>"
  }
}

Guardás el key completo como JSON local (~/.prysmid/key.json).

Scopes disponibles

Scope	Permite
workspace:read	Listar y leer recursos del workspace. Sin escrituras.
workspace:write	Lo de read + crear/editar apps, IdPs, branding, webhooks.
workspace:admin	Lo de write + cambiar plan, crear/revocar machine keys, borrar workspace (con confirm).
tenant:<slug>:read	Restringido a un tenant específico, solo lectura.
tenant:<slug>:write	Restringido a un tenant, R/W.

Las claves restringidas a tenant son útiles cuando un cliente tuyo enterprise quiere automatizar SU lado vía agente sin acceder a otros tenants.

Precaución

Empezá con el scope más bajo que sirva. Es trivial elevarlo después generando una nueva key. Es complicado bajarlo si ya está distribuida en N agentes.

Cómo el agente la usa

El MCP server (@prysmid/mcp) lee la key de PRYSMID_MACHINE_KEY_PATH. La intercambia por un access_token corto-lived (15 min) cada vez que conecta. Cuando llama a un tool, manda el access_token en Authorization: Bearer. El plano de control valida scope y firma, y deja pasar o rechaza.

Vos no tenés que mover tokens manualmente. La machine key es el secret long-lived; el token es ephemeral.

Rotación

curl -X POST https://api.prysmid.com/v1/workspaces/$WS/machine-keys/$KEY_ID/rotate \
  -H "Authorization: Bearer $TOKEN"

Genera nueva key con mismo scope/expiración. La vieja queda válida 24 horas — tiempo suficiente para que actualices el JSON local en cada agente sin downtime. Después de 24h, la vieja queda revocada automáticamente.

Revocación inmediata

Si comprometieron una key (alguien commiteó por error a un repo público, te robaron la laptop, etc.):

curl -X DELETE https://api.prysmid.com/v1/workspaces/$WS/machine-keys/$KEY_ID \
  -H "Authorization: Bearer $TOKEN"

Inmediato. Cualquier access_token ya emitido contra esa key sigue válido hasta 15 min más, después rebota. Si necesitás revocación instantánea total, pedí también a soporte invalidación de tokens activos.

Lo que machine keys NO te dan

• No son passes universales. Son por workspace. Si operás 5 workspaces, tenés 5 keys (una por workspace) o un workspace “ops” con tenants.
• No habilitan login de end users. Para esto está OIDC + clientes OAuth, no machine keys.
• No te dan acceso al motor de auth low-level directamente. Solo al plano de control. Si necesitás operar a más bajo nivel, generá una service-account key dedicada desde Settings → Service accounts.

Buenas prácticas

• Una machine key por integración. No reuses una para 3 agentes — si comprometen uno, perdés todos.
• Expiración explícita. Aunque “no expira” está disponible, ponele 1 año por default. Te obliga a revisar.
• Naming descriptivo. claude-desktop-fernando-2026-04 mejor que key1. Cuando tengas 20 keys vas a agradecer.
• Audit periódico. keys.list y eliminá las que no reconozcas o no recuerdes.