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

# Get Started with the Atlas Administration API

**Important:**

Each Atlas Administration API has its own resources and requires initial setup.

You can access the Atlas Administration API servers through the public Internet only. The Atlas Administration API is not available over connections that use [network peering](https://www.mongodb.com/docs/atlas/security-vpc-peering.md#std-label-vpc-peering) or [private endpoints.](https://www.mongodb.com/docs/atlas/security-configure-private-endpoints.md#std-label-private-endpoint)

To learn more, see [Atlas Programmatic Access.](https://www.mongodb.com/docs/atlas/api.md#std-label-atlas-api)

The Atlas Administration API follows the principles of the REST (Representational State Transfer) architectural style to expose a number of internal resources which enable programmatic access to administrative features in Atlas. To learn more about the Atlas Administration API, see [Atlas Administration API Reference.](https://www.mongodb.com/docs/atlas/api/atlas-admin-api-ref.md#std-label-atlas-admin-api-ref)

The Atlas Administration API doesn't provide access to the data stored in your clusters. To read or write data in a database, you must authenticate to your cluster using the credentials for a [database user](https://www.mongodb.com/docs/manual/reference/database-users.md#std-label-security-database-users) with the appropriate read or write [roles](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#std-label-database-user-roles). You can use the Atlas Administration API to create and manage database users.

To use the Atlas Administration API to manage your Atlas clusters, you must authenticate your API (Application Programming Interface) requests with one of the following authentication methods:

- Service account access tokens ([OAuth 2.0)](https://oauth.net/2/)

- API keys ([HTTP Digest Authentication)](http://en.wikipedia.org/wiki/Digest_access_authentication)

To learn about these methods, see [Atlas Administration API Authentication Methods.](https://www.mongodb.com/docs/atlas/api/api-authentication.md#std-label-api-authentication)

The following sections describe how to use service accounts and API (Application Programming Interface) keys to configure programmatic access to your Atlas organizations and projects.

**Note:**

The MongoDB Atlas Shared Responsibility Model defines the complementary duties of MongoDB and its customers in maintaining a secure and resilient data environment. Under this framework, MongoDB manages the security and operational integrity of the underlying platform, while customers are responsible for the configuration, management, and data policies of their specific deployments. For a detailed breakdown of ownership across security and operational excellence, see [Shared Responsibility Model.](https://www.mongodb.com/resources/products/fundamentals/shared-responsibility)

## Before You Begin

Before configuring programmatic access, confirm the following:

- You have an Atlas account. To create one, see [Create an Atlas Account.](https://www.mongodb.com/docs/atlas/tutorial/create-atlas-account.md#std-label-create-atlas-account)

- An Atlas organization exists. To create one, see [Create an Organization.](https://www.mongodb.com/docs/atlas/access/orgs-create-view-edit-delete.md#std-label-create-organization)

## Required Access

To create a service account or API (Application Programming Interface) keys for an organization, you must have [`Organization Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Organization-Owner) access to that organization.

To grant a service account access to a project, you must have [`Organization Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Organization-Owner) access to the organization that owns the project.

To grant API (Application Programming Interface) keys access to a project, you must have [`Project Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Owner) access for that project.

## Optional: Require an IP Access List

When you create an organization using the Atlas UI, Atlas requires an IP access list for the Atlas Administration API. This limits API (Application Programming Interface) requests to only those from the location-based IP or CIDR (Classless Inter-Domain Routing) addresses that you specify in the IP access list. If you make a request to the Atlas Administration API without an IP access list entry, the server responds with a 403 status code.

If you disable this feature, you can make API (Application Programming Interface) requests from any address on the Internet as long as the IP access list is empty. Once you add an IP access list entry, only requests originating from that IP address can make requests.

**Note:**

[IP access lists](https://www.mongodb.com/docs/atlas/security/ip-access-list.md#std-label-access-list) apply to *using* service account access tokens, not [creating](https://www.mongodb.com/docs/atlas/api/service-accounts/generate-oauth2-token.md#std-label-generate-oauth2-token-atlas) or [revoking](https://www.mongodb.com/docs/atlas/api/service-accounts/revoke-oauth2-token.md#std-label-revoke-oauth2-token-atlas) them. You can generate a token from any IP address, but you can only use it to call the API (Application Programming Interface) if your IP address is on the access list.

**Note:**

IP access lists apply only to programmatic API keys and service accounts. They don't apply to other types of access to the Atlas Administration API, such as the Atlas CLI or delegated access granted through Atlas App Connections. Delegated access includes third-party partner applications, MongoDB applications such as MongoDB Compass, and Model Context Protocol (MCP) clients. If your organization requires all Atlas Administration API traffic to originate from specific addresses, don't enable delegated app access for that organization. Delegated access settings for partner applications and MCP clients are off by default in existing organizations.

To set your organization to require IP access lists for every Atlas Administration API request after organization creation, follow these steps:

1. In Atlas, go to the Organization Settings page.

   If it's not already displayed, select your desired organization from the  Organizations menu in the navigation bar.

   In the sidebar, click Organization Settings.

   The [Organization Settings](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%23%2Forg%2F%3Corganization%3E%2Fsettings%2Fgeneral) page displays.

2. Toggle the Require IP Access List for the Atlas Administration API setting to On.

## Grant Programmatic Access to an Organization

To set up programmatic access to an organization, you must:

- [Create a service account.](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-create-service-account-org)

- [Generate an access token for your service account.](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-gen-access-token-service-account-atlas-ui)

### Create a Service Account for an Organization

Use the following procedure to grant programmatic access to an organization by creating a service account and generating a new client secret. To learn more about authentication methods for the Atlas Administration API, see [Atlas Administration API Authentication Methods.](https://www.mongodb.com/docs/atlas/api/api-authentication.md#std-label-api-authentication)

1. In Atlas, go to the Applications page.

   If it's not already displayed, select your desired organization from the  Organizations menu in the navigation bar.

   Click Applications in the sidebar under the Identity & Access section.

   The [Applications](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%23%2Forg%2F%3Corganization%3E%2Faccess%2FserviceAccounts) page displays.

2. Click Add new  Service Account.

3. Enter the service account information.

   Enter a Name.

   Enter a Description.

   Select a duration from the Client Secret Expiration menu.

   From the **Organization Permissions** menu, select the [new role or roles](https://www.mongodb.com/docs/atlas/reference/user-roles.md#std-label-organization-roles) for the service account.

   These roles determine the permissions of the access tokens generated by this service account. You use access tokens to authenticate to the Atlas Administration API when you [make an API request.](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-example-api-request)

   You can also assign project-level roles to the service account after you create it. To learn how, see [Grant Existing Service Account Access to a Project.](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-invite-org-app-api-keys)

4. Click Create.

5. Copy and save the Client Secret.

   The client secret acts as the password when creating access tokens.

   **Warning:**

   *This is the only time you can view the full client secret.* Click Copy and save it to a secure location. Otherwise, you'll need to generate a new client secret.

6. Add an API Access List Entry.

   Click Add Access List Entry.

   Enter an IP (Internet Protocol) address or CIDR (Classless Inter-Domain Routing) block from which you want Atlas to accept API (Application Programming Interface) requests for this service account.

   You can also click Use Current IP Address if the host you are using to access Atlas will also make API (Application Programming Interface) requests using this service account.

   Click Save.

### Generate an Access Token for your Service Account

After you create a service account, you can generate an access token for it. You use access tokens to authenticate API (Application Programming Interface) requests to the Atlas Administration API. For an example, see [Make an API (Application Programming Interface) Request.](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-example-api-request)

To generate an access token for a service account:

1. Retrieve the client secret for your service account.

   Locate the client secret beginning with `mdb_sa_sk_` that you saved immediately after [creating the service account](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-see-org-api-keys), which was the only time you could view the client secret. If you did not save the client secret, you must generate a new client secret.

2. Base64-encode the client ID and secret.

   For example, run:

   ```sh
   echo -n {clientId}:{clientSecret} | base64 -w0
   ```

3. Request an access token.

   Replace `{base64Auth}` in the following example with the output from the preceding step, then run:

   ```sh
   curl --request POST \
      --url https://cloud.mongodb.com/api/oauth/token \
      --header 'accept: application/json' \
      --header 'cache-control: no-cache' \
      --header 'authorization: Basic {base64Auth}' \
      --header 'content-type: application/x-www-form-urlencoded' \
      --data 'grant_type=client_credentials'
   ```

   **Output:**

   ```sh
   {"access_token":"{accessToken}","expires_in":3600,"token_type":"Bearer"}%
   ```

   **Tip: Service Account Token Best Practices**

   Consider the following best practices when using service account tokens:

   - **Reuse tokens**: Service account access tokens have a 1 hour (3600 seconds) lifespan, during which you can reuse the token multiple times. Avoid creating new tokens for every request.

   - **Generate new tokens when needed**: While you can't refresh an access token, you can [generate a new token](https://www.mongodb.com/docs/atlas/api/service-accounts/generate-oauth2-token.md#std-label-generate-oauth2-token-atlas) when your current token is close to expiry. This prevents service interruptions and allows you to maintain authorized service account access.

   - **Revoke unnecessary tokens**: When you no longer need a token, [revoke the token's access](https://www.mongodb.com/docs/atlas/api/service-accounts/revoke-oauth2-token.md#std-label-revoke-oauth2-token-atlas) to minimize security risks and ensure that only active tokens have access to your service account.

To set up programmatic access to an organization, you must:

- [Create a service account.](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-create-service-account-atlas-api)

- [Generate an access token for your service account.](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-gen-access-token-service-account-atlas-api)

### Create a Service Account for an Organization

You can use the Atlas Administration API to [create a service account for your organization.](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-createserviceaccount)

After you've created the service account, copy and save the `{CLIENT-ID}` and `{CLIENT-SECRET}` from the output, which should look similar to the following example. *This is the only time you can view the full client secret.* You'll need this information when you [make an API request.](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-example-api-request)

```sh
{
  "createdAt" : "2024-04-23T17:47:17Z",
  "description" : "Service account for my organization.",
  "clientId" : "{CLIENT-ID}",
  "name" : "My Service Account",
  "roles" : [ "ORG_MEMBER" ],
  "secrets" : [ {
    "createdAt" : "2024-04-23T17:47:17Z",
    "expiresAt" : "2024-12-01T00:00:00Z",
    "id" : "6627f7259d39d858378c9e30",
    "lastUsedAt" : null,
    "secret" : "{CLIENT-SECRET}"
   } ]
}%
```

### Generate an Access Token for your Service Account

After you create a service account, you can generate an access token for it. You use access tokens to authenticate API (Application Programming Interface) requests to the Atlas Administration API. For an example, see [Make an API (Application Programming Interface) Request.](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-example-api-request)

To generate an access token for a service account:

1. Retrieve the client secret for your service account.

   Locate the client secret beginning with `mdb_sa_sk_` that you saved immediately after [creating the service account](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-see-org-api-keys), which was the only time you could view the client secret. If you did not save the client secret, you must generate a new client secret.

2. Base64-encode the client ID and secret.

   For example, run:

   ```sh
   echo -n {clientId}:{clientSecret} | base64 -w0
   ```

3. Request an access token.

   Replace `{base64Auth}` in the following example with the output from the preceding step, then run:

   ```sh
   curl --request POST \
      --url https://cloud.mongodb.com/api/oauth/token \
      --header 'accept: application/json' \
      --header 'cache-control: no-cache' \
      --header 'authorization: Basic {base64Auth}' \
      --header 'content-type: application/x-www-form-urlencoded' \
      --data 'grant_type=client_credentials'
   ```

   **Output:**

   ```sh
   {"access_token":"{accessToken}","expires_in":3600,"token_type":"Bearer"}%
   ```

   **Tip: Service Account Token Best Practices**

   Consider the following best practices when using service account tokens:

   - **Reuse tokens**: Service account access tokens have a 1 hour (3600 seconds) lifespan, during which you can reuse the token multiple times. Avoid creating new tokens for every request.

   - **Generate new tokens when needed**: While you can't refresh an access token, you can [generate a new token](https://www.mongodb.com/docs/atlas/api/service-accounts/generate-oauth2-token.md#std-label-generate-oauth2-token-atlas) when your current token is close to expiry. This prevents service interruptions and allows you to maintain authorized service account access.

   - **Revoke unnecessary tokens**: When you no longer need a token, [revoke the token's access](https://www.mongodb.com/docs/atlas/api/service-accounts/revoke-oauth2-token.md#std-label-revoke-oauth2-token-atlas) to minimize security risks and ensure that only active tokens have access to your service account.

### Create API (Application Programming Interface) Keys for an Organization

1. In Atlas, go to the Applications page.

   If it's not already displayed, select your desired organization from the  Organizations menu in the navigation bar.

   Click Applications in the sidebar under the Identity & Access section.

   The [Applications](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%23%2Forg%2F%3Corganization%3E%2Faccess%2FserviceAccounts) page displays.

2. Click Add new  API Key.

3. Enter the API Key Information.

   Enter a Description.

   In the Organization Permissions menu, select the [new role or roles](https://www.mongodb.com/docs/atlas/reference/user-roles.md#std-label-organization-roles) for the API (Application Programming Interface) key.

4. Click Next.

5. Copy and save the Public Key.

   The public key acts as the username when making API requests.

6. Copy and save the Private Key.

   The private key acts as the password when making API requests.

   **Warning: Copy and save Public and Private Keys**

   The Private Key is only shown once: *on this page*. Click the Copy button to add the Private Key to the clipboard. Save and secure both the Public and Private Keys.

7. Add an API Access List Entry.

   Click Add Access list Entry.

   Enter an IP (Internet Protocol) address or CIDR (Classless Inter-Domain Routing) block from which you want Atlas to accept API (Application Programming Interface) requests for this API (Application Programming Interface) Key.

   You can also click Use Current IP Address if the host you are using to access Atlas will also make API (Application Programming Interface) requests using this API (Application Programming Interface) Key.

   Click Save.

8. Click Done.

### Create API (Application Programming Interface) Keys for an Organization

To create an API key in an organization using the Atlas CLI, run the following command:

```sh

atlas organizations apiKeys create [options]

```

To learn more about the command syntax and parameters, see the Atlas CLI documentation for [atlas organizations apiKeys create.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-organizations-apiKeys-create/)

### Add an API (Application Programming Interface) Access List Entry for the API (Application Programming Interface) Key

To create an IP access list entry for your API key using the Atlas CLI, run the following command:

```sh

atlas organizations apiKeys accessLists create [options]

```

To learn more about the command syntax and parameters, see the Atlas CLI documentation for [atlas organizations apiKeys accessLists create.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-organizations-apiKeys-accessLists-create/)

## Grant Programmatic Access to a Project

To learn more about these two authentication methods, see [Atlas Administration API Authentication Methods.](https://www.mongodb.com/docs/atlas/api/api-authentication.md#std-label-api-authentication)

To give API (Application Programming Interface) keys access to a project, you must have [`Project Access Manager`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Access-Manager) or [`Project Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Owner) access for that project.

### Grant Existing Service Account Access to a Project

If you've already created service accounts or API (Application Programming Interface) keys for an organization, you can assign them to a project to grant that project access to the Atlas Administration API.

**Warning:**

If you assign an organization service account to a project, the [`Project Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Owner) can manage the service account, including rotating secrets and updating the IP access list.

1. In Atlas, go to the Users page.

   If it's not already displayed, select your desired organization from the  Organizations menu in the navigation bar.

   Click All Projects in the sidebar under the Identity & Access section, and select your desired project.

   Click Project Identity & Access in the sidebar under the Security section.

   The [Users](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Faccess) page displays.

2. Click Invite to Project.

3. Locate your organization service account.

   Start typing the client ID of your service account in the field, then select your service account from the menu.

4. Assign project roles to your service account.

   In the menu that appears, select the [new role or roles](https://www.mongodb.com/docs/atlas/reference/user-roles.md#std-label-project-roles) for the service account.

5. Click Invite to Project.

### Grant Existing Service Account Access to a Project

You can use the Atlas Administration API to [grant an existing service account access to a project.](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-addprojectserviceaccount)

### Grant Existing API (Application Programming Interface) Keys Access to a Project

If you've already created service accounts or API (Application Programming Interface) keys for an organization, you can assign them to a project to grant that project access to the Atlas Administration API.

1. In Atlas, go to the Users page.

   If it's not already displayed, select your desired organization from the  Organizations menu in the navigation bar.

   Click All Projects in the sidebar under the Identity & Access section, and select your desired project.

   Click Project Identity & Access in the sidebar under the Security section.

   The [Users](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Faccess) page displays.

2. Click Invite to Project.

3. Add the API Key to the project.

   Type the public key into the field.

   In the Project Permissions menu, select the [new role or roles](https://www.mongodb.com/docs/atlas/reference/user-roles.md#std-label-project-roles) for the API (Application Programming Interface) key.

4. Click Invite to Project.

### Grant Existing API (Application Programming Interface) Keys Access to a Project

If you've already created service accounts or API (Application Programming Interface) keys for an organization, you can assign them to a project to grant that project access to the Atlas Administration API.

To assign an API key to a project using the Atlas CLI, run the following command:

```sh

atlas projects apiKeys assign <ID> [options]

```

To learn more about the command syntax and parameters, see the Atlas CLI documentation for [atlas projects apiKeys assign.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-projects-apiKeys-assign/)

### Add Project Access from a Project

If you haven't already created a service account or API (Application Programming Interface) keys for an organization, you can create them for a project to grant that project access to the Atlas Administration API. The service account or API (Application Programming Interface) keys that you create for a project are automatically added to the parent organization with the permission [`Organization Member`.](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Organization-Member)

To create a service account for a project using the Atlas UI:

1. In Atlas, go to the Users page.

   If it's not already displayed, select your desired organization from the  Organizations menu in the navigation bar.

   Click All Projects in the sidebar under the Identity & Access section, and select your desired project.

   Click Project Identity & Access in the sidebar under the Security section.

   The [Users](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Faccess) page displays.

2. Click Create Application  Service Account.

3. Enter the service account information.

   Enter a Name.

   Enter a Description.

   Select a duration from the Client Secret Expiration menu.

   From the **Project Permissions** menu, select the [new role or roles](https://www.mongodb.com/docs/atlas/reference/user-roles.md#std-label-project-roles) for the service account.

4. Click Create.

5. Copy and save the Client Secret.

   The client secret acts as the password when creating access tokens.

   **Warning:**

   *This is the only time you can view the full client secret.* Click Copy and save it to a secure location. Otherwise, you'll need to generate a new client secret.

6. Add an API Access List Entry.

   Click Add Access List Entry.

   Enter an IP (Internet Protocol) address or CIDR (Classless Inter-Domain Routing) block from which you want Atlas to accept API (Application Programming Interface) requests for this service account.

   You can also click Use Current IP Address if the host you are using to access Atlas will also make API (Application Programming Interface) requests using this service account.

   Click Save.

You can use the Atlas Administration API to [create a service account for your project.](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-createprojectserviceaccount)

After you've created the service account, copy and save the `{CLIENT-ID}` and `{CLIENT-SECRET}` from the output, which should look similar to the following example. *This is the only time you can view the full client secret.* You'll need this information when you [make an API request.](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-example-api-request)

```sh
{
  "createdAt" : "2024-04-23T17:47:17Z",
  "description" : "Service account for my organization.",
  "clientId" : "{CLIENT-ID}",
  "name" : "My Service Account",
  "roles" : [ "ORG_MEMBER" ],
  "secrets" : [ {
    "createdAt" : "2024-04-23T17:47:17Z",
    "expiresAt" : "2024-12-01T00:00:00Z",
    "id" : "6627f7259d39d858378c9e30",
    "lastUsedAt" : null,
    "secret" : "{CLIENT-SECRET}"
   } ]
}%
```

To create an API key for your project using the Atlas CLI, run the following command:

```sh

atlas projects apiKeys create [options]

```

To learn more about the command syntax and parameters, see the Atlas CLI documentation for [atlas projects apiKeys create.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-projects-apiKeys-create/)

After you create the API (Application Programming Interface) key for your project, use the Atlas UI to add an API (Application Programming Interface) access list entry. You can't use the API (Application Programming Interface) key for the project until you set up the API (Application Programming Interface) access list.

**Note: Atlas CLI Limitation**

You can't edit the API (Application Programming Interface) access list for a project API (Application Programming Interface) key using the Atlas CLI.

To add an API (Application Programming Interface) access list entry using the Atlas UI:

1. Add an API Access List Entry.

   Click Add Access List Entry.

   Enter an IP (Internet Protocol) address from which you want Atlas to accept API (Application Programming Interface) requests for this API (Application Programming Interface) Key. You can also click Use Current IP Address if the host you are using to access Atlas will also make API (Application Programming Interface) requests using this API (Application Programming Interface) Key.

   Click Save.

2. Click Done.

To create an API (Application Programming Interface) key for a project using the Atlas UI:

1. In Atlas, go to the Users page.

   If it's not already displayed, select your desired organization from the  Organizations menu in the navigation bar.

   Click All Projects in the sidebar under the Identity & Access section, and select your desired project.

   Click Project Identity & Access in the sidebar under the Security section.

   The [Users](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Faccess) page displays.

2. Click Create Application  API Key.

3. Enter the API Key Information.

   On the Create API Key page:

   Enter a Description.

   In the Project Permissions menu, select the [new role or roles](https://www.mongodb.com/docs/atlas/reference/user-roles.md#std-label-project-roles) for the API (Application Programming Interface) key.

4. Click Next.

5. Copy and save the Public Key.

   The public key acts as the username when making API requests.

6. Copy and save the Private Key.

   The private key acts as the password when making API requests.

   **Warning: Save Private Key**

   The Private Key is only shown once: *on this page*. Click the Copy button to add the Private Key to the clipboard. Save and secure both the Public and Private Keys.

7. Add an API Access List Entry.

   Click Add Access List Entry.

   Enter an IP (Internet Protocol) address from which you want Atlas to accept API (Application Programming Interface) requests for this API (Application Programming Interface) Key.

   You can also click Use Current IP Address if the host you are using to access Atlas will also make API (Application Programming Interface) requests using this API (Application Programming Interface) Key.

   Click Save.

8. Click Done.

## Make an API (Application Programming Interface) Request

The Atlas Administration API uses one of two authentication methods to authenticate requests: service account or API (Application Programming Interface) keys. You'll need the keys or secret that you saved when [configuring your preferred authentication method](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-create-org-api-key) to complete the following procedures.

All Atlas Administration API endpoints have the following base URL:

`https://cloud.mongodb.com/api/atlas/<version>`

**Important:**

MongoDB uses HTTPS URLs to increase security. Using HTTP URLs will return a 301 status code.

To make an API (Application Programming Interface) request using a service account, use the service account to generate an access token, then use the access token in your request:

1. Retrieve the client secret for your service account.

   Locate the client secret beginning with `mdb_sa_sk_` that you saved immediately after [creating the service account](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-see-org-api-keys), which was the only time you could view the client secret. If you did not save the client secret, you must generate a new client secret.

2. Base64-encode the client ID and secret.

   For example, run:

   ```sh
   echo -n {clientId}:{clientSecret} | base64 -w0
   ```

3. Request an access token.

   Make a `POST` request to the [cloud.mongodb.com/api/oauth/token](https://www.mongodb.com/docs/atlas/api/service-accounts/generate-oauth2-token.md#std-label-generate-oauth2-token-atlas) endpoint to generate an access token for your service account.

   Replace `{base64Auth}` in the following example with the output from the preceding step, then run:

   ```sh
   curl --request POST \
      --url https://cloud.mongodb.com/api/oauth/token \
      --header 'accept: application/json' \
      --header 'cache-control: no-cache' \
      --header 'authorization: Basic {base64Auth}' \
      --header 'content-type: application/x-www-form-urlencoded' \
      --data 'grant_type=client_credentials'
   ```

   **Output:**

   ```sh
   {"access_token":"{accessToken}","expires_in":3600,"token_type":"Bearer"}%
   ```

   **Important:**

   The access token is valid for 1 hour (3600 seconds). You can't refresh an access token. When this access token expires, repeat this step to generate a new one.

4. Make an API (Application Programming Interface) call.

   Replace `{accessToken}` in the following example with the output from the preceding step.

   The following sample `GET` request [returns all projects](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-/listgroups) in your organization:

   ```sh
   curl --request GET \
        --url https://cloud.mongodb.com/api/atlas/v2/groups \
        --header 'Authorization: Bearer {accessToken}' \
        --header 'Accept: application/vnd.atlas.2023-02-01+json' \
        --header 'Content-Type: application/json'
   ```

   The following sample `POST` request takes a request body and [creates a project](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-/creategroup) named `MyProject` in your organization:

   ```sh
   curl --header 'Authorization: Bearer {accessToken}' \
         --header "Content-Type: application/json" \
         --header "Accept: application/vnd.atlas.2023-02-01+json" \
         --include \
         --request POST "https://cloud.mongodb.com/api/atlas/v2/groups" \
         --data '
            {
               "name": "MyProject",
               "orgId": "5a0a1e7e0f2912c554080adc"
            }'
   ```

To make an API (Application Programming Interface) request using a service account, use the service account to generate an access token, then use the access token in your request:

1. Retrieve the client secret for your service account.

   Locate the client secret beginning with `mdb_sa_sk_` that you saved immediately after [creating the service account](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-see-org-api-keys), which was the only time you could view the client secret. If you did not save the client secret, you must generate a new client secret.

2. Base64-encode the client ID and secret.

   For example, run:

   ```sh
   echo -n {clientId}:{clientSecret} | base64 -w0
   ```

3. Request an access token.

   Make a `POST` request to the [cloud.mongodb.com/api/oauth/token](https://www.mongodb.com/docs/atlas/api/service-accounts/generate-oauth2-token.md#std-label-generate-oauth2-token-atlas) endpoint to generate an access token for your service account.

   Replace `{base64Auth}` in the following example with the output from the preceding step, then run:

   ```sh
   curl --request POST \
      --url https://cloud.mongodb.com/api/oauth/token \
      --header 'accept: application/json' \
      --header 'cache-control: no-cache' \
      --header 'authorization: Basic {base64Auth}' \
      --header 'content-type: application/x-www-form-urlencoded' \
      --data 'grant_type=client_credentials'
   ```

   **Output:**

   ```sh
   {"access_token":"{accessToken}","expires_in":3600,"token_type":"Bearer"}%
   ```

   **Important:**

   The access token is valid for 1 hour (3600 seconds). You can't refresh an access token. When this access token expires, repeat this step to generate a new one.

4. Make an API (Application Programming Interface) call.

   Replace `{accessToken}` in the following example with the output from the preceding step.

   The following sample `GET` request [returns all projects](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-/listgroups) in your organization:

   ```sh
   curl --request GET \
        --url https://cloud.mongodb.com/api/atlas/v2/groups \
        --header 'Authorization: Bearer {accessToken}' \
        --header 'Accept: application/vnd.atlas.2023-02-01+json' \
        --header 'Content-Type: application/json'
   ```

   The following sample `POST` request takes a request body and [creates a project](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-/creategroup) named `MyProject` in your organization:

   ```sh
   curl --header 'Authorization: Bearer {accessToken}' \
         --header "Content-Type: application/json" \
         --header "Accept: application/vnd.atlas.2023-02-01+json" \
         --include \
         --request POST "https://cloud.mongodb.com/api/atlas/v2/groups" \
         --data '
            {
               "name": "MyProject",
               "orgId": "5a0a1e7e0f2912c554080adc"
            }'
   ```

Your request should resemble the following examples, where `{PUBLIC-KEY}` is your API (Application Programming Interface) public key and `{PRIVATE-KEY}` is the corresponding private key. To explore the available endpoints through the Atlas Administration API, you can use the [Postman workspace for MongoDB.](https://www.postman.com/mongodb-devrel/workspace/mongodb-atlas-administration-apis/overview)

The following sample `GET` request [returns all projects](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-/listgroups) in your organization:

```sh
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
      --header "Content-Type: application/json" \
      --header "Accept: application/vnd.atlas.2024-08-05+json" \
      --include \
      --request GET "https://cloud.mongodb.com/api/atlas/v2/groups"
```

The following sample `POST` request takes a request body and [creates a project](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-/creategroup) named `MyProject` in your organization:

```sh
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
      --header "Content-Type: application/json" \
      --header "Accept: application/vnd.atlas.2024-08-05+json" \
      --include \
      --request POST "https://cloud.mongodb.com/api/atlas/v2/groups" \
      --data '
         {
            "name": "MyProject",
            "orgId": "5a0a1e7e0f2912c554080adc"
         }'
```

Your request should resemble the following examples, where `{PUBLIC-KEY}` is your API (Application Programming Interface) public key and `{PRIVATE-KEY}` is the corresponding private key. To explore the available endpoints through the Atlas Administration API, you can use the [Postman workspace for MongoDB.](https://www.postman.com/mongodb-devrel/workspace/mongodb-atlas-administration-apis/overview)

The following sample `GET` request [returns all projects](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-/listgroups) in your organization:

```sh
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
      --header "Content-Type: application/json" \
      --header "Accept: application/vnd.atlas.2024-08-05+json" \
      --include \
      --request GET "https://cloud.mongodb.com/api/atlas/v2/groups"
```

The following sample `POST` request takes a request body and [creates a project](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-/creategroup) named `MyProject` in your organization:

```sh
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
      --header "Content-Type: application/json" \
      --header "Accept: application/vnd.atlas.2024-08-05+json" \
      --include \
      --request POST "https://cloud.mongodb.com/api/atlas/v2/groups" \
      --data '
         {
            "name": "MyProject",
            "orgId": "5a0a1e7e0f2912c554080adc"
         }'
```

**See also:**

- [Atlas Administration API Specification](https://mongodb.com/docs/atlas/reference/api-resources-spec)

- [Atlas Administration API Error Codes](https://www.mongodb.com/docs/atlas/reference/api-errors.md#std-label-atlas-api-error-codes)

Alternatively, you can use any tool that supports [OpenAPI v3 specification](https://spec.openapis.org/oas/v3.0.1) to generate code samples or mock servers. For example, you can import the [Atlas Admin API Specification](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/) into [Postman](https://www.postman.com/) to generate `curl` commands.

**Warning:**

Using an HTTP URL with Postman will return a 301 status code as expected. However, in this scenario, Postman may automatically retry the request with HTTPS, but simultaneously strip the header and body from the retry request. This will return a 401 status code instead of 301, making it difficult to determine why the request failed.

To use Postman to generate `curl` commands:

1. In the MongoDB Atlas Administration API [documentation](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/), click Download source in the navigation bar.

2. Right-click the OpenAPI specification format you want to download and copy the link.

3. Open Postman and click File, then Import.

   The Import window displays.

4. In the Import window, click Link and paste the download link that you copied in step 2.

5. Click Continue, then Import.

6. For the request for which you want to generate a `curl` command, click **\</>** on the right and select cURL from the Code snippet dropdown.

## Next Steps

To learn more about the Atlas Administration API, see [Atlas Administration API Reference.](https://www.mongodb.com/docs/atlas/api/atlas-admin-api-ref.md#std-label-atlas-admin-api-ref)

To manage programmatic access to the Atlas Administration API, see any of the following procedures:

- [Manage Programmatic Access to an Organization.](https://www.mongodb.com/docs/atlas/configure-api-access-org.md#std-label-atlas-admin-api-access-org)

- [Manage Programmatic Access to Multiple Organizations.](https://www.mongodb.com/docs/atlas/configure-api-access-mult-org.md#std-label-prog-access-mult-orgs)

- [Manage Programmatic Access to a Project.](https://www.mongodb.com/docs/atlas/configure-api-access-project.md#std-label-atlas-admin-api-access-project)

- [Rotate Service Account Secrets.](https://www.mongodb.com/docs/atlas/tutorial/rotate-service-account-secrets.md#std-label-rotate-service-account-secrets)