> This page location: /docs.md > /docs/agentengine.md

> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Manage Service Account Credentials

MongoDB Atlas Agent Engine is in Public Preview and intended for evaluation and prototyping purposes only. We do not recommend production deployments during preview and expect to communicate breaking changes with you periodically. To learn more about preview feature considerations, see [Preview Features](https://www.mongodb.com/docs/preview-features/).

## Overview

In this guide, you can learn how to manage the credentials that authenticate an application to the Atlas Agent Engine API. The Atlas Agent Engine accepts service account access tokens on its API routes. These tokens work on the project and organization management routes and on the agent invocation routes.

To authenticate your own account with the `agentengine` CLI instead, see [Install and Authenticate.](https://www.mongodb.com/docs/agentengine/build/install-authenticate.md#std-label-agent-engine-set-up-install-authenticate)

**Note: Public Preview**

The Atlas Agent Engine public API is subject to change during Public Preview. Endpoints, request formats, and response formats might change without a backward-compatible migration path.

To maintain compatibility with future API versions, see the [pinning API contracts](https://www.mongodb.com/docs/agentengine/reference/limitations.md#std-label-agent-engine-api-contract-pinning) section.

To review all limitations that apply during Public Preview, see [MongoDB Atlas Agent Engine Limitations.](https://www.mongodb.com/docs/agentengine/reference/limitations.md#std-label-agent-engine-limitations)

## Authenticate with a Service Account

A service account is an account that belongs to a project or an organization instead of to a person. Use a service account when an application server invokes agents on behalf of its own users, so that your application does not depend on an individual credential.

### 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.

#### Use the API

To create a service account, send a `POST` request to the `/api/v1/projects/{id}/service-accounts` endpoint.

In the following requests, `$SESSION_TOKEN` is your own session token from logging in to the Atlas Agent Engine. You can't manage service accounts with a service account's access token. The Atlas Agent Engine defines the owner of a new service account from the session token, so every request that creates, rotates, deactivates, or restricts a service account must come from a signed-in user who holds the required role.

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

The `secret_expires_after_hours` field is optional and defaults to `2160` hours, which is 90 days. The response resembles the following output:

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

**Important:**

Save the client secret when the Atlas Agent Engine displays it. The Atlas Agent Engine shows the secret only at creation.

Service account client IDs start with `ae_sa_id_`, and client secrets start with `ae_sa_sk_`. To create an organization-scoped service account, you must have the `ORG_GROUP_CREATOR` role. Send a `POST` request to the `/api/v1/organizations/{id}/service-accounts` endpoint:

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

The response has the same format as the project-scoped response.

#### Use the UI

You can create and manage service accounts in the Atlas Agent Engine UI. For a project-scoped service account, click Service Accounts in the project navigation. For an organization-scoped service account, go to Organization
Settings and click Service Accounts.

#### Use the CLI

You can also create and manage service accounts with the `agentengine` CLI. The following command creates a project-scoped service account:

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

To create an organization-scoped service account, pass `--org-id` instead of `--project-id`. If you pass neither, the CLI uses the project from your current login state, and falls back to your organization when no project is selected.

The following flags are available:

| Flag | Description |
| --- | --- |
| `--role` | *(Required)* The role to grant the service account. This flag accepts exactly one role. For a project-scoped account, pass `PROJECT_OWNER` or `PROJECT_READ_ONLY`. For an organization-scoped account, pass `ORG_OWNER`, `ORG_GROUP_CREATOR`, or `ORG_READ_ONLY`. |
| `--project-id` | Project scope for the service account. Pass only one of `--project-id` or `--org-id`. |
| `--org-id` | Organization scope for the service account. Pass only one of `--project-id` or `--org-id`. |
| `--description` | A human-readable description of the service account. |
| `--secret-expires-in` | The secret lifetime as a duration in whole hours, such as `720h`. Defaults to the server default of `2160h`. |
| `--ip-access-list` | Restricts the addresses that can use the credential. Defaults to unrestricted. |

The `service-account` command also provides the `list`, `get`, `rotate`, and `delete` subcommands, which accept the same scope flags.

### 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:

```bash
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:

```json
{
  "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:

```bash
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. An organization-scoped service account with the `ORG_OWNER` role can invoke agents in Atlas-backed projects and Atlas Agent Engine-managed projects, but only in projects in its own organization. To invoke an agent in an Atlas-backed project with any other role, 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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.

## Service Account Roles

A service account has exactly one role. The following table shows the roles that you can assign the service account at each scope:

| Scope | Roles |
| --- | --- |
| Project | `PROJECT_OWNER`, `PROJECT_READ_ONLY` |
| Organization | `ORG_OWNER`, `ORG_GROUP_CREATOR`, `ORG_READ_ONLY` |

Both scopes can invoke agents, but not every role can. To invoke an agent, a project-scoped service account must have the `PROJECT_OWNER` role, and an organization-scoped service account must have the `ORG_GROUP_CREATOR` or `ORG_OWNER` role. You can assign the `PROJECT_READ_ONLY` or `ORG_READ_ONLY` role to a service account, but a service account with either role can't invoke agents. Only assign a read-only role to a service account that doesn't invoke agents. The Atlas Agent Engine reevaluates the service account's status and roles on every request, so a role change or a deactivation applies to the account's next request.

**Note:**

Service account roles use Atlas role names. The available roles are `PROJECT_OWNER`, `PROJECT_READ_ONLY`, `ORG_OWNER`, `ORG_GROUP_CREATOR`, and `ORG_READ_ONLY`.

## Restrict IP Addresses

To limit the IP addresses that can use a service account's token, set an IP access list. Send a `PUT` request to the endpoint for the account's scope with the full list of allowed IP addresses and CIDR blocks. For a project-scoped account, use the following endpoint:

```bash
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"]}'
```

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

```bash
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"]}'
```

The request replaces the entire IP access list. To remove IP restrictions, send an empty array to the endpoint. The Atlas Agent Engine rejects requests that use the service account's access token from an address that is not on the list. The IP access list doesn't restrict token requests.

## Next Steps

To learn how to call a deployed agent with these credentials, see [Invoke an Agent.](https://www.mongodb.com/docs/agentengine/deploy/invoke-agent.md#std-label-agent-engine-invoke-agent)
