Docs Menu
Docs Home
/ /
Atlas App Services
/

Create an App Services App

On this page

  • Overview
  • Before You Begin
  • Procedure

You can create a new App Services App from the App Services UI, CLI, or Admin API.

An App Services App is a managed backend instance that contains your application's services. Each app belongs to a specific Atlas project.

To create an App in a project, you must be logged in to MongoDB Atlas and have Project Owner permissions.

You will need the following to create an App in the Atlas UI:

  • A MongoDB Atlas account with Project Owner permissions. To learn how to sign up for a free account, see Get Started with Atlas.

You will need the following to create an App in the CLI:

  • A MongoDB Atlas account with Project Owner permissions. To learn how to sign up for a free account, see Get Started with Atlas.

  • A MongoDB Atlas Admin API public/private key pair. The API key must have Project Owner permissions to work with App Services Admin API.

  • A copy of App Services CLI installed and added to your local system PATH. To learn how, see Install App Services CLI.

You will need the following to create an App with the Admin API:

1

In the Atlas UI Project dashboard, click the App Services tab.

2

You can either create a new blank App or start from a template that has some services pre-configured for you. Some template Apps also come with corresponding client applications.

To learn more, see Template Apps.

If the project has no Apps, you will be prompted to either create a new App from a template or to start from scratch.

Otherwise, you can choose between two create buttons at the top right of the App Services tab:

  • To create a blank App, click the Create a New App button.

  • To use a template, click the Create App from Template and select a template from the dropdown menu.

3

The UI prompts you to configure the following settings:

  • The Application Name. Your App name is public and included in the App ID used by clients.

    Note

    App Name Limitations

    Application names must be between 1 and 32 characters and may only contain ASCII letters, numbers, underscores, and hyphens.

  • A Linked Data Source. This is an Atlas cluster that the App can access. If the project has no clusters, you can have App Services create one for you automatically.

    Note

    MongoDB Version 5.0 or Higher Required

    Atlas Device Sync requires an Atlas cluster running MongoDB version 5.0 or later. When setting up your cluster, select MongoDB 5.0 (or a later version) from the dropdown menu under Additional Settings.

You can also configure the following optional settings under Advanced Configuration:

4

Once you've configured the App, click Create App Service.

Upon creation of your App, the Atlas UI automatically redirects you to the App Services Admin UI.

1

Use your MongoDB Atlas Admin API Key to log in to the CLI:

appservices login --api-key="<my api key>" --private-api-key="<my private api key>"
2

The CLI can create an app and copy its configuration files to a local directory with a single command. The command asks you to specify the app name and the Atlas project that should contain the app. You can configure the command with flags or interactively.

appservices apps create

The command also supports additional flags that you can optionally include to customize your app. The following table lists common flags you might use:

--template

Choose an App template to start from. If you don't specify a template, the command creates a blank app.

For a list of all template apps, see to Available Template Apps.

--deployment-model

Defines the App's deployment model.

Valid values:

  • GLOBAL

  • LOCAL

--provider-region

Defines the App's deployment region.

For a list of available regions, see Cloud Deployment Regions.

--environment

Sets the App's environment tag.

Valid values:

  • development

  • testing

  • qa

  • production

Tip

See also:

For more details and additional flags, see the CLI documentation for the create command.

1

Call the admin user authentication endpoint with your MongoDB Atlas API key pair:

curl -X POST \
https://services.cloud.mongodb.com/api/admin/v3.0/auth/providers/mongodb-cloud/login \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"username": "<Public API Key>",
"apiKey": "<Private API Key>"
}'

If authentication succeeds, the response body contains a JSON object with an access_token value:

{
"access_token": "<access_token>",
"refresh_token": "<refresh_token>",
"user_id": "<user_id>",
"device_id": "<device_id>"
}

The access_token grants access to the App Services Admin API. You must include it as a Bearer token in the Authorization header for all Admin API requests.

2

Every App Services App belongs to a MongoDB Atlas project.

To create a App you need the Project ID (sometimes referred to as the Group ID) of the MongoDB Atlas project that contains the app. You will include this ID in the URL of API requests.

3

You can create a new App through the Create an App endpoint.

Your request must include:

curl -X POST \
https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps \
--header 'Authorization: Bearer <access_token>' \
--data '{ "name": "<App Name>" }'

If you want to create an app from a template, you must also include the following in the request body:

  • The template_id field with one of the available template apps. For a list of all template apps, refer to Available Template Apps.

  • The data_source field with information about an existing Atlas cluster.

    curl -X POST \
    https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps \
    -H 'Authorization: Bearer <access_token>' \
    -d '{
    "name": "<App Name>",
    "template_id": "<Template App Id>",
    "data_source": {
    "name": "mongodb-atlas",
    "type": "mongodb-atlas",
    "config": {
    "clusterName": "<Atlas Cluster Name>"
    }
    }
    }'

If your App is created successfully, the API returns a 201 response with information about your new App.

Back

Develop & Deploy Apps

Next

Get App Metadata