Gerenciar chaves de API e contas de serviço

Criar uma Conta de Serviço

Esta seção descreve como criar uma conta de serviço usando a API, a UI e a CLI agentengine.

Para criar uma conta de serviço com escopo de projeto, você deve ter a função PROJECT_OWNER no projeto.

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 um token de acesso

Troque o ID do cliente e o segredo do cliente por um token de acesso enviando uma solicitação POST para o endpoint /api/v1/oauth/token. Passe as credenciais como credenciais HTTP Basic, conforme mostrado no exemplo a seguir, ou como campos client_id e client_secret no corpo da solicitação:

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

O campo grant_type aceita apenas o valor client_credentials. A resposta se assemelha à seguinte saída:

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

O token de acesso é válido por uma hora. Solicite um novo token antes que o atual expire. O Atlas Agent Engine controla a taxa de solicitações de token para cada conta de serviço e retorna um código de erro 429 quando um cliente solicita tokens com muita frequência.

Invoque um agente com um token de acesso

Envie um token de acesso no cabeçalho Authorization de um pedido de invocação para invocar um agente com um token de acesso:

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!"}'

Uma conta de serviço com escopo de projeto pode atuar apenas em seu próprio projeto. Se o caminho da solicitação nomear qualquer outro projeto, o Atlas Agent Engine rejeitará sua solicitação. Uma conta de serviço com escopo de organização deve nomear um projeto em sua própria organização.

A função ORG_GROUP_CREATOR por si só não concede acesso de invocação a todos os projeto da organização. Uma conta de serviço no escopo da organização com a função ORG_GROUP_CREATOR pode invocar agentes somente em projetos gerenciados pelo Atlas Agent Engine. Para invocar um agente em um projeto apoiado pelo Atlas, use uma conta de serviço com escopo de projeto com a função PROJECT_OWNER.

Girar e desativar contas de serviço

Para substituir o segredo de uma conta de serviço, envie uma solicitação de POST para o ponto de extremidade de rotação do escopo da conta. Para uma conta com escopo de projeto, use o seguinte endpoint:

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 uma conta com escopo organizacional, use o seguinte endpoint:

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}'

O campo secret_expires_after_hours é opcional e o padrão é 2160 horas. Para aceitar o padrão, omita o corpo da solicitação. A resposta tem o mesmo formato que a resposta de criação e contém o novo segredo. O segredo anterior permanece válido por até sete dias ou até sua própria expiração, o que ocorrer primeiro.

Para desativar o segredo anterior imediatamente, gire o segredo uma segunda vez ou desative a conta. Ambas as ações interrompem a autenticação do segredo anterior. Use um deles quando precisar revogar um segredo que pode estar comprometido.

Para desativar uma conta de serviço, envie uma solicitação de DELETE para o endpoint para o escopo da conta. Para uma conta com escopo de projeto, use o seguinte endpoint:

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

Para uma conta com escopo organizacional, use o seguinte endpoint:

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

Depois de desativar uma conta de serviço, a conta não pode mais solicitar tokens, e qualquer token que ela já tenha falhará na próxima solicitação.