Create an Atlas Ephemeral Cluster

Create the Ephemeral cluster.

Send a POST request to the following endpoint:

https://cloud.mongodb.com/api/atlas/v2/unauth/ephemeralClusters:create

The request requires the following Accept header:

'Accept: application/vnd.atlas.preview+json'

The following example request creates an Ephemeral cluster named Cluster0:

curl -sS -X POST 'https://cloud.mongodb.com/api/atlas/v2/unauth/ephemeralClusters:create' \
  -H 'Accept: application/vnd.atlas.preview+json' \
  -H 'Content-Type: application/json' \
  -d '{"clusterName": "Cluster0"}'

The create endpoint returns a response in the following format:

{
  "claimUrl": "https://account.mongodb.com/account/register?claimId={claimId}",
  "clusterId": "{clusterId}",
  "connectionString": "mongodb+srv://{username}:{password}@{host}/",
  "expiresAt": "{timestamp}",
  "status": "PROVISIONING",
  "termsOfService": "By using this API and any resources provisioned through it, you agree to be bound by MongoDB's Cloud Terms of Service at https://www.mongodb.com/legal/terms-and-conditions/cloud; and Privacy Policy at https://www.mongodb.com/legal/privacy/privacy-policy."
}

The response includes the following fields:

• claimUrl: Unique URL for claiming this Ephemeral cluster. A human must open this URL in a browser. Valid for 7 days after the cluster is created.

• clusterId: Unique identifier of the Ephemeral cluster. To retrieve the cluster's status, claimUrl, and other details, send a GET request to the following endpoint, replacing {clusterId} with this value:

  https://cloud.mongodb.com/api/atlas/v2/unauth/ephemeralClusters/{clusterId}

  To learn more, see Return One Ephemeral Atlas Cluster.

• connectionString: Connection string that uses the mongodb+srv:// protocol to connect to the Ephemeral cluster. Includes the username and password for an autogenerated database user that can read and write data in the cluster. Any client that uses this connection string authenticates as this database user. The create response is the only time that Atlas returns the unredacted password.

• expiresAt: Date and time when Atlas pauses the cluster if it isn't claimed. A paused Ephemeral cluster is inaccessible until you claim it. The timestamp uses the ISO 8601 format in UTC.

• status: Status of the Ephemeral cluster. One of PROVISIONING, ACTIVE, or PAUSED.

• termsOfService: Notice that by using this API, you agree to MongoDB's Cloud Terms of Service and Privacy Policy. Includes a link to the full terms.

To learn more about the create endpoint, see Create One Ephemeral Atlas Cluster.

Save the connection string and claim values.

From the create response, save the connectionString, claimUrl, and clusterId. You need them to connect to, claim, and retrieve the details of the cluster.

Connect to the Ephemeral cluster.

Use the connectionString value from the create response to connect to the Ephemeral cluster from a compatible environment, such as:

• Application code: Provide the connection string to the MongoDB driver for your programming language when you initialize the client object that connects to the cluster. This is the typical choice when connecting from an application. To learn more, see Connect to a Cluster via Client Libraries.

• Command line: Provide the connection string as an argument to the MongoDB Shell (mongosh) to connect and run commands interactively:

  Example command line connection

  mongosh "<connectionString>"

To learn more about available connection methods, see Considerations.

(Optional) Claim the Ephemeral cluster.

Claiming the Ephemeral cluster is optional. If you don't claim the cluster, Atlas pauses it 2 days after creation and deletes it 7 days after creation. When you claim the cluster, Atlas converts it into a standard Free cluster with no expiration date. The claimed cluster keeps all of its data, and the connection string you saved continues to work with the same credentials. To learn more about the effects of claiming, see Claim an Ephemeral Cluster.

To claim the cluster, a human must sign in to Atlas in a browser. Choose one of the following options:

• Claim now: Share the claimUrl only with the person who will claim the cluster. They can follow the procedure in Claim an Ephemeral Cluster to claim the cluster.

• Claim later: Save the claimUrl in a secure location that remains available to the person who will claim the cluster. That person can then claim the cluster any time within 7 days of creation.

• Claim never: Take no action. Atlas deletes the cluster 7 days after creation.

Sign in to Atlas from the claim URL.

1. In a web browser, open the claimUrl that you saved from the create response to reach the Atlas sign-in page. The claim URL has the following format, where {claimId} is a unique identifier for the Ephemeral cluster:

   https://account.mongodb.com/account/register?claimId={claimId}

2. On the sign-in page, sign in to Atlas with an existing account, or create a new account. When you claim the cluster in the next step, this account gains both database and administrative access to the cluster.

   If you create a new account, verify your email before you continue.

Configure and claim the Ephemeral cluster.

After you sign in, Atlas displays the claim page. On this page, do the following:

1. From the drop-down, select an existing organization, or select Create new org for this cluster to create one. When you claim the cluster, Atlas moves it into the selected organization and creates a project for it there.

   Important

   The drop-down lists only organizations where your Atlas account has the Organization Owner role. When you claim the cluster, every Organization Owner in the selected organization can manage the cluster and its data.

2. Configure IP access. To restrict access, remove 0.0.0.0/0 and allow only your current IP address (recommended). To allow connections from any IP address, keep 0.0.0.0/0. You can restrict IP access later in the project's Network Access settings.

3. Click Claim Cluster. This is a one-time action that you can't undo.

Review the confirmation page.

After you claim the cluster, Atlas displays a confirmation page with the organization and project names, the cluster details, and your chosen IP access configuration.

Click Go To Project Overview to view the claimed cluster in the Atlas UI.

(Optional) Reconfigure the claimed cluster.

You can reconfigure the claimed cluster and its project using the Atlas UI, Atlas CLI, or Atlas Administration API. At the cluster level, you can scale the cluster to a higher tier to increase storage. At the project level, you can manage database users and restrict IP access to increase security. To learn more, see Manage Clusters.