Overview
在本指南中，您可以学习；了解如何管理向Atlas Agent Engine API对应用程序进行身份验证的凭证。 Atlas Agent Engine 在其API路由上接受API密钥和服务帐户访问权限令牌。这些凭证适用于项目和组织管理路由以及代理调用路由。
要使用 agentengine CLI对自己的帐户进行身份验证，请参阅安装和身份验证。
注意
公开预览期间的API稳定性
Atlas Agent Engine 公共API在公共预览期间可能会发生变化。如果没有向后兼容的迁移路径，端点、请求格式和响应格式可能会发生变化。固定您的自动化依赖的 agentengine CLI版本，并在升级之前查看发布说明。
使用服务帐户进行身份验证
服务帐户是属于项目或组织而不是个人的帐户。当应用程序服务器代表其用户调用代理时，请使用服务帐户，这样您的应用程序就不会依赖于单个档案。
重要
服务帐户内存身份
当服务帐户调用已部署的代理时， Atlas Agent Engine 会使用服务帐户自己的身份作为运行时内存身份。平台会忽略调用请求或 agentengine invoke --user-id 标志提供的任何最终用户 user_id 值。
自动轮流记录、提取、合并和 app.memory 操作会使用此已解析身份。因此，通过同一服务帐户进行身份验证的调用股票一个内存用户作用域。
此限制仅适用于服务帐户调用的已部署代理。独立运行的、项目范围的内存服务不受影响。此服务继续接受来自调用者的显式 user_id 和 session_id 值。
要按最终用户隔离内存，请从应用程序中调用独立运行内存服务，并将显式 user_id 和 session_id 值传递给每个调用。要学习；了解更多信息，请参阅使用独立内存服务。
创建服务帐户
本部分介绍如何使用API、 用户界面和 agentengine CLI创建服务帐户。
要创建项目范围的服务帐户，您必须具有项目的 PROJECT_OWNER角色。
使用API
要创建服务帐号，请向 /api/v1/projects/{id}/service-accounts 端点发送 POST请求。
在以下请求中，$SESSION_TOKEN 是您自己的登录Atlas助手引擎的会话令牌。您无法使用服务帐户的访问权限令牌管理服务帐户。 Atlas Agent Engine 通过会话令牌定义新服务帐户的所有者，因此创建、轮换、停用或限制服务帐户的每个请求都必须来自拥有所需角色的登录用户。
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 }'
secret_expires_after_hours字段为可选字段，默认值为 2160 小时，即 90 天。响应输出类似于以下内容：
{ "client_secret": "ae_sa_sk_...", "service_account": { "client_id": "ae_sa_id_...", "name": "my-app-server", "is_active": true } }
重要
在Atlas助手引擎显示客户端密钥时保存客户端密钥。 Atlas Agent Engine 仅在创建时显示密钥。
服务帐户客户端ID 以 ae_sa_id_ 开头，客户端密钥以 ae_sa_sk_ 开头。要创建组织范围的服务帐号，您必须具有 ORG_GROUP_CREATOR角色。向 /api/v1/organizations/{id}/service-accounts 端点发送 POST请求：
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 }'
响应的格式与项目范围的响应相同。
使用用户界面
您可以在Atlas Agent Engine用户界面中创建和管理服务帐户。对于项目范围的服务帐户，请单击项目导航中的 Service Accounts。对于组织范围的服务帐户，请转到 Organization Settings 并单击 Service Accounts。
使用CLI
您还可以使用 agentengine CLI创建和管理服务帐户。以下命令创建一个项目范围的服务帐户：
agentengine service-account create my-app-server \ --project-id $PROJECT_ID \ --role PROJECT_OWNER \ --description "Invokes agents from the support app"
要创建组织范围的服务帐户，请传递 --org-id 而不是 --project-id。如果两者均未通过，CLI将使用当前登录状态下的项目，并在未选择项目时回退到您的组织。
以下标志可用：
标记 | 说明 |
|---|---|
| （必需）授予服务帐户的角色。该标志只接受一个角色。对于项目范围的帐户，请传递 |
| 服务帐户的项目范围。仅传递 |
| 服务帐户的组织作用域。仅传递 |
| 服务帐户的人类可读描述。 |
| 以小时为单位的持续时间的密钥生命周期，例如 |
| 限制可以使用该档案的地址。默认为无限制。 |
service-account 命令还提供 list、get、rotate 和 delete 子命令，它们接受相同的作用域标志。
请求访问令牌
通过向 /api/v1/oauth/token 端点发送 POST请求，用客户端ID和客户端密钥交换访问权限令牌。将凭证作为HTTP基本凭证传递（如以下示例所示），或作为请求正文中的 client_id 和 client_secret 字段传递：
curl -s "https://agentengine.mongodb.com/api/v1/oauth/token" \ -X POST \ -u "$CLIENT_ID:$CLIENT_SECRET" \ -d "grant_type=client_credentials"
grant_type字段仅接受 client_credentials 值。响应输出类似于以下内容：
{ "access_token": "...", "token_type": "Bearer", "expires_in": 3600 }
访问权限令牌的有效期为一小时。在当前令牌过期之前请求新令牌。 Atlas助手引擎控制每个服务帐户的令牌请求速率，并在客户端请求令牌过于频繁时返回 429 错误代码。
使用访问令牌调用代理
在调用请求的Authorization 标头中发送访问权限令牌，以使用访问权限令牌调用代理：
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!"}'
项目范围的服务帐户只能对自己的项目执行操作。如果请求路径指定了任何其他项目，则Atlas Agent Engine 将拒绝其请求。组织范围的服务帐户必须在其自己的组织中命名项目。
仅凭 ORG_GROUP_CREATOR角色并不能授予对组织中每个项目的访问权限。具有 ORG_GROUP_CREATOR角色的组织范围服务帐号只能调用Atlas助手引擎管理的项目中的助手。要调用 Atlas 支持的项目中的代理，请使用具有 PROJECT_OWNER角色的项目范围的服务帐户。
轮换和停用服务帐户
要替换服务帐户的密钥，请向该帐户范围的轮换端点发送 POST请求。对于项目范围的帐户，请使用以下端点：
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}'
对于组织范围的帐户，请使用以下端点：
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}'
secret_expires_after_hours字段为可选字段，默认值为 2160 小时。要接受默认，请省略请求正文。该响应的格式与创建响应相同，并包含新密钥。之前的密钥有效期最长为 7 天，或直到其过期为止，以先到者为准。
要立即停用以前的密钥，请再次轮换密钥或停用帐户。这两个操作都会阻止以前的密钥进行身份验证。当必须撤销可能泄露的密钥时，请使用其中之一。
要停用服务帐户，请向该帐户范围的端点发送 DELETE请求。对于项目范围的帐户，请使用以下端点：
curl -s "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/service-accounts/$CLIENT_ID" \ -X DELETE \ -H "Authorization: Bearer $SESSION_TOKEN"
对于组织范围的帐户，请使用以下端点：
curl -s "https://agentengine.mongodb.com/api/v1/organizations/$ORG_ID/service-accounts/$CLIENT_ID" \ -X DELETE \ -H "Authorization: Bearer $SESSION_TOKEN"
停用服务帐户后，该帐户无法再请求令牌，并且其已持有的任何令牌在下一次请求时都会失败。
服务帐户角色
一个服务帐户只有一个角色。下表显示了您可以在每个作用域为服务帐号分配的角色：
范围 | 角色 |
|---|---|
项目 |
|
组织 |
|
两个作用域都可以调用代理，但并非每个角色都可以。要调用代理，项目范围的服务帐户必须具有 PROJECT_OWNER角色，组织范围的服务帐户必须具有 ORG_GROUP_CREATOR角色。您可以将 PROJECT_READ_ONLY 和 ORG_READ_ONLY 角色分配给服务帐号，但具有任一角色的服务帐号都无法调用代理。仅将只读角色分配给不调用代理的服务帐户。 Atlas Agent Engine 在每次请求时重新评估服务帐户的状态和角色，因此角色更改或停用会应用于该帐户的下一次请求。
限制IP地址
要限制可以使用服务帐户令牌的IP地址，设立IP访问列表。向帐户范围的端点发送 PUT请求，其中包含允许的IP地址和 CIDR 块的完整列表。对于项目范围的帐户，请使用以下端点：
curl -s "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/service-accounts/$CLIENT_ID/ip-access-list" \ -X PUT \ -H "Authorization: Bearer $SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{"ip_access_list": ["203.0.113.0/24"]}'
对于组织范围的帐户，请使用以下端点：
curl -s "https://agentengine.mongodb.com/api/v1/organizations/$ORG_ID/service-accounts/$CLIENT_ID/ip-access-list" \ -X PUT \ -H "Authorization: Bearer $SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{"ip_access_list": ["203.0.113.0/24"]}'
该请求将替换整个IP访问列表。要删除IP限制，请向端点发送一个空大量。 Atlas Agent Engine 会拒绝来自不在列表中的解决且使用服务帐户访问权限令牌的请求。 IP访问列表不限制令牌请求。