Cuentas de servicio¶

Una cuenta de servicio es un miembro de tu organización que no es una persona sino un programa: una integración, un script que se ejecuta por la noche, otro sistema que llama a OS. Todo lo que una persona puede hacer en OS, una cuenta de servicio puede hacerlo mediante la API, decidido exactamente de la misma manera. Esta página es para administradores: quienes tienen el rol de administrador de la organización.

Una clave puede hacer exactamente lo que puede su cuenta de servicio, y nada más. Quien tiene una clave actúa como la cuenta de servicio. Si das pocos derechos a una cuenta de servicio, sus claves también dan pocos derechos. Da, pues, a una cuenta de servicio solo lo que el programa necesita de verdad.

En la pantalla¶

Abra Gestión de usuarios, elija Cuentas de servicio y recorra:

La lista. Verá sus cuentas de servicio. Elija Crear una cuenta de servicio para crear una.
Crear. Rellene Nombre y, si lo desea, Descripción, elija los roles, grupos y valores de atributo que recibe (solo puede dar lo que usted mismo tiene) y elija Crear cuenta de servicio.
Claves. Abra la cuenta de servicio y elija la pestaña Claves. Elija Crear una nueva clave API, rellene Nombre de la clave API y Fecha de caducidad y elija Crear clave API. La pantalla muestra el Secreto una sola vez, con el Client-id y la Dirección del token: guárdelo enseguida. En cada clave ve el estado, cuándo caduca, cuándo se usó por última vez y sus advertencias. Cuando una clave caduca en menos de 14 días, los administradores de la organización reciben además una notificación en OS y por correo, una vez por fecha de caducidad. La copia antigua de una clave rotada no avisa.
Rotar. En una clave activa elija Rotar, indique la nueva fecha de caducidad y el Solapamiento en horas y confirme. La pantalla muestra el nuevo secreto una sola vez. Solo quien tiene todo lo que tiene la cuenta de servicio recibe este botón.
Revocar. En una clave elija la papelera y confirme. La clave deja de funcionar.
Permisos. La pestaña Permisos muestra los roles, grupos y valores de atributo de la cuenta de servicio. Elija Añadir derechos para dar alguno, o retire uno; solo puede dar y retirar lo que usted mismo puede.
Acceso. La pestaña Acceso muestra, por tipo de elemento, lo que la cuenta de servicio puede hacer (Ver, Usar, Cambiar, Eliminar), y por tanto también lo que puede hacer quien tenga su clave. Mire aquí antes de crear una clave.
Desactivar y eliminar. Arriba en la página elija Desactivar (o Activar) o Eliminar.

Crear una cuenta de servicio¶

Elige un nombre (único en tu organización) y, si quieres, una descripción de para qué sirve.
Elige los roles, grupos y valores de atributos que recibirá, como en una invitación. Solo puedes dar lo que tú mismo tienes (por qué).
La cuenta de servicio está activa de inmediato. No hay nadie que acepte una invitación.

Una cuenta de servicio aparece en la misma lista de miembros que las personas, con los mismos roles, grupos y atributos. Solo quien administra cuentas de servicio las modifica, de la misma manera que a una persona; un administrador de personas ve una cuenta de servicio en la lista, pero no la modifica. Una cuenta de servicio no cuenta como último administrador: una organización mantiene siempre a una persona con el rol de administrador.

Lo que una cuenta de servicio no puede hacer¶

Lo que una persona hace solo para sí misma, una cuenta de servicio no puede hacerlo: configurar preferencias, hacerse borrar y aceptar una invitación. OS lo rechaza con 403. Una cuenta de servicio la administra y la elimina un administrador.

Claves¶

Un programa se identifica con una clave. Una cuenta de servicio puede tener varias claves (por defecto, como máximo cinco a la vez), cada una con su propio nombre.

Crea una clave con un nombre y una fecha de caducidad. Es obligatoria y está como máximo un año en el futuro.
OS muestra el secreto de la clave una sola vez, con el client-id y la dirección donde el programa pide un token. Guarda el secreto de inmediato en un lugar seguro; OS no vuelve a mostrarlo nunca.
Tras unos segundos, la clave funciona.

Solo quien tiene todo lo que tiene la cuenta de servicio puede crearle una clave. Así nadie puede obtener mediante una clave más derechos de los que ya tiene.

El programa pide un token con el client-id y el secreto, y envía ese token a OS:

curl -s -X POST "$TOKEN_ENDPOINT" \
  -d grant_type=client_credentials -d client_id="$CLIENT_ID" -d client_secret="$CLIENT_SECRET"

Un token es válido cinco minutos; después el programa pide uno nuevo.

Sustituir sin interrupción¶

Rota una clave: OS crea una clave nueva con un secreto nuevo, y la antigua sigue funcionando durante un solapamiento (por defecto 24 horas, como máximo 30 días). Pon el secreto nuevo en el programa antes de que termine el solapamiento.

Revocar, caducar y avisos¶

Una clave revocada deja de funcionar desde la siguiente solicitud.
Una clave caducada deja de funcionar desde su fecha de caducidad.
En cada clave ves cuándo la vio usar OS por última vez (con cinco minutos de precisión). OS avisa de una clave que caduca en menos de 14 días, que no se ha usado en 30 días, o que una semana después de crearse aún no se ha usado nunca.

Usar por MCP¶

Tu propio agente que habla MCP puede trabajar con OS como la cuenta de servicio, con los permisos de la cuenta: cada operación de la API de OS es entonces una herramienta. Abre la cuenta de servicio; en la pestaña General, Usar por MCP muestra:

la Dirección MCP, adonde el agente envía sus llamadas;
la Dirección del token, donde el agente obtiene un token;
Obtener un token y Listar las herramientas: dos ejemplos para copiar.

Usa el ID de cliente de una clave de la pestaña Claves y el secreto de esa clave. Pon el secreto donde está YOUR_CLIENT_SECRET y el token del primer paso donde está ACCESS_TOKEN:

curl -s -X POST '<direccion-del-token>' \
  -d grant_type=client_credentials \
  -d client_id='<id-de-cliente>' \
  -d client_secret='YOUR_CLIENT_SECRET'

curl -s -X POST '<direccion-mcp>' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Un token es válido cinco minutos; después obtén uno nuevo. Si la cuenta de servicio no tiene ninguna clave activa, la tarjeta dice que crees una primero. Mientras las apps de IA estén en Desactivado en la organización, cada llamada del agente se rechaza hasta que un administrador lo active (Trabajar desde apps de IA); la tarjeta también lo dice.

Qué puede hacer una cuenta de servicio y qué hizo¶

En cada cuenta de servicio ves, por tipo de elemento, lo que puede hacer. En el registro de auditoría ves lo que hizo y lo que se hizo con la cuenta de servicio y sus claves. Los secretos nunca están en el registro.

Desactivar y eliminar¶

Desactivar: desde la siguiente solicitud, OS rechaza a la cuenta de servicio todo en la organización, con cualquier clave; solo GET /api/v1/me sigue respondiendo, sin membresía. Volver a activar hace utilizables de nuevo las mismas claves.
Eliminar: definitivo. Se revocan todas las claves. Lo que la cuenta de servicio creó en las funciones de IA sigue siendo de la organización, salvo que elijas borrarlo.

Si OS rechaza¶

401: la clave está revocada o caducada, o el token es de otro cliente.
403: das un rol, grupo o valor que tú mismo no tienes, o creas una clave para una cuenta de servicio que tiene más que tú; el mensaje indica qué.
409: el nombre ya está en uso, la cuenta de servicio ya tiene el número máximo de claves, o la cuenta de servicio se ha modificado entretanto.
422: una fecha de caducidad que falta, ya ha pasado o está demasiado lejos en el futuro.

Mediante la API¶

POST /api/v1/organisations/{id}/service-accounts con name y, opcionalmente, description, roles, groups y attributes, como en una invitación.
GET, PATCH (con If-Match) y DELETE /api/v1/organisations/{id}/service-accounts/{account_id}.
POST /api/v1/organisations/{id}/service-accounts/{account_id}/keys con label y expires_at; la respuesta contiene client_id, client_secret y token_endpoint.
POST …/keys/{key_id}/rotate con expires_at y overlap_hours; DELETE …/keys/{key_id} revoca una clave.
GET /api/v1/organisations/{id}/memberships/{account_id}/access muestra lo que puede hacer; GET /api/v1/organisations/{id}/audit-events?actor={account_id} lo que hizo.