Administrar claves API y cuentas de servicio

Crea una cuenta de servicio

Esta sección describe cómo crear una cuenta de servicio utilizando la API, la interfaz de usuario y la interfaz de línea de comandos agentengine.

Para crear una cuenta de servicio con ámbito de proyecto, debe tener el rol PROJECT_OWNER en el proyecto.

curl -s "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/service-accounts" \
  -X POST \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "my-app-server",
        "description": "Invokes agents from the support app",
        "roles": ["PROJECT_OWNER"],
        "secret_expires_after_hours": 2160
      }'

{
  "client_secret": "ae_sa_sk_...",
  "service_account": {
    "client_id": "ae_sa_id_...",
    "name": "my-app-server",
    "is_active": true
  }
}

curl -s "https://agentengine.mongodb.com/api/v1/organizations/$ORG_ID/service-accounts" \
  -X POST \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "my-app-server",
        "description": "Invokes agents from the support app",
        "roles": ["ORG_GROUP_CREATOR"],
        "secret_expires_after_hours": 2160
      }'

agentengine service-account create my-app-server \
  --project-id $PROJECT_ID \
  --role PROJECT_OWNER \
  --description "Invokes agents from the support app"

Solicitar un token de acceso

Intercambie el ID de cliente y el secreto de cliente por un token de acceso enviando una solicitud POST al punto final /api/v1/oauth/token. Pase las credenciales como credenciales HTTP básicas, como se muestra en el siguiente ejemplo, o como campos client_id y client_secret en el cuerpo de la solicitud:

curl -s "https://agentengine.mongodb.com/api/v1/oauth/token" \
  -X POST \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials"

El campo grant_type solo acepta el valor client_credentials. La respuesta se asemeja a la siguiente salida:

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600
}

El token de acceso es válido durante una hora. Solicite un nuevo token antes de que caduque el actual. El motor del agente Atlas controla la frecuencia de las solicitudes de token para cada cuenta de servicio y devuelve un código de error 429 cuando un cliente solicita tokens con demasiada frecuencia.

Invocar un agente con un token de acceso.

Envíe un token de acceso en el encabezado Authorization de una solicitud de invocación para invocar un agente con un token de acceso:

curl -s "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/invoke" \
  -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, agent!"}'

Una cuenta de servicio con ámbito de proyecto solo puede actuar sobre su propio proyecto. Si la solicitud hace referencia a cualquier otro proyecto, el motor del agente de Atlas la rechaza. Una cuenta de servicio con ámbito de organización debe especificar un proyecto dentro de su propia organización.

El rol ORG_GROUP_CREATOR por sí solo no otorga acceso de invocación a todos los proyectos de la organización. Una cuenta de servicio con ámbito de organización y el rol ORG_GROUP_CREATOR solo puede invocar agentes en los proyectos que administra Atlas Agent Engine. Para invocar un agente en un proyecto respaldado por Atlas, utilice una cuenta de servicio con ámbito de proyecto y el rol PROJECT_OWNER.

Rotar y desactivar cuentas de servicio

Para reemplazar el secreto de una cuenta de servicio, envíe una solicitud POST al punto final de rotación para el ámbito de la cuenta. Para una cuenta con ámbito de proyecto, utilice el siguiente punto final:

curl -s "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/service-accounts/$CLIENT_ID/rotate" \
  -X POST \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"secret_expires_after_hours": 2160}'

Para una cuenta con ámbito de organización, utilice el siguiente punto final:

curl -s "https://agentengine.mongodb.com/api/v1/organizations/$ORG_ID/service-accounts/$CLIENT_ID/rotate" \
  -X POST \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"secret_expires_after_hours": 2160}'

El campo secret_expires_after_hours es opcional y su valor predeterminado es 2160 horas. Para aceptar el valor predeterminado, omita el cuerpo de la solicitud. La respuesta tiene el mismo formato que la respuesta de creación y contiene el nuevo secreto. El secreto anterior permanece válido hasta por siete días o hasta su vencimiento, lo que ocurra primero.

Para desactivar la clave secreta anterior de inmediato, gírela una segunda vez o desactive la cuenta. Ambas acciones impiden que la clave secreta anterior se autentique. Utilice una de ellas cuando deba revocar una clave secreta que pueda estar comprometida.

Para desactivar una cuenta de servicio, envíe una solicitud DELETE al punto final correspondiente al ámbito de la cuenta. Para una cuenta con ámbito de proyecto, utilice el siguiente punto final:

curl -s "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/service-accounts/$CLIENT_ID" \
  -X DELETE \
  -H "Authorization: Bearer $SESSION_TOKEN"

Para una cuenta con ámbito de organización, utilice el siguiente punto final:

curl -s "https://agentengine.mongodb.com/api/v1/organizations/$ORG_ID/service-accounts/$CLIENT_ID" \
  -X DELETE \
  -H "Authorization: Bearer $SESSION_TOKEN"

Tras desactivar una cuenta de servicio, esta ya no podrá solicitar tokens, y cualquier token que posea fallará en su siguiente solicitud.