Manage API Keys and Service Accounts

Create a Service Account

This section describes how to create a service account by using the API, the UI, and the agentengine CLI.

To create a project-scoped service account, you must have the PROJECT_OWNER role on the project.

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"

Request an Access Token

Exchange the client ID and client secret for an access token by sending a POST request to the /api/v1/oauth/token endpoint. Pass the credentials as HTTP Basic credentials, as shown in the following example, or as client_id and client_secret fields in the request body:

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

The grant_type field accepts only the client_credentials value. The response resembles the following output:

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

The access token is valid for one hour. Request a new token before the current one expires. The Atlas Agent Engine controls the rate of token requests for each service account and returns a 429 error code when a client requests tokens too frequently.

Invoke an Agent with an Access Token

Send an access token in the Authorization header of an invocation request to invoke an agent with an access token:

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

A project-scoped service account can act only on its own project. If the request path names any other project, the Atlas Agent Engine rejects its request. An organization-scoped service account must name a project in its own organization.

The ORG_GROUP_CREATOR role alone doesn't grant invoke access to every project in the organization. An organization-scoped service account with the ORG_GROUP_CREATOR role can invoke agents only in projects that the Atlas Agent Engine manages. To invoke an agent in an Atlas-backed project, use a project-scoped service account with the PROJECT_OWNER role.

Rotate and Deactivate Service Accounts

To replace a service account's secret, send a POST request to the rotation endpoint for the account's scope. For a project-scoped account, use the following 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}'

For an organization-scoped account, use the following 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}'

The secret_expires_after_hours field is optional and defaults to 2160 hours. To accept the default, omit the request body. The response has the same format as the creation response and contains the new secret. The previous secret remains valid for up to seven days or until its own expiration, whichever comes first.

To deactivate the previous secret immediately, rotate the secret a second time or deactivate the account. Both actions stop the previous secret from authenticating. Use one of them when you must revoke a secret that might be compromised.

To deactivate a service account, send a DELETE request to the endpoint for the account's scope. For a project-scoped account, use the following endpoint:

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

For an organization-scoped account, use the following endpoint:

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

After you deactivate a service account, the account can no longer request tokens, and any token that it already holds fails on its next request.