Data API Endpoints

On this page

When to Use the Data API

Base URL
Set Up the Data API
Authentication
Authorization
Response Type
Access Permissions
API Versions
Call a Data API Endpoint
Choose an API Version
Specify the Request Data Format
Choose a Response Data Format
Authenticate the Request
Authorize the Request

Realm is now Atlas Device SDK – Learn More

The Data API lets you securely read and write data using standard HTTPS requests. The API includes automatically generated endpoints that each represent a MongoDB operation. You can use the endpoints to create, read, update, delete, and aggregate documents in a MongoDB data source.

For example, this POST request stores a document in a linked cluster by calling the insertOne endpoint:

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/insertOne" \
  -X POST \
  -H "Content-Type: application/ejson" \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "hello",
    "document": {
      "text": "Hello, world!"
    }
  }'

{ "insertedId": "5f1a785e1536b6e6992fd588" }

For a detailed API reference of all available endpoints, see the Data API OpenAPI Reference.

Note

Data API Endpoints are not supported in private endpoints.

When to Use the Data API

You can use the Data API to integrate with any app or service that supports HTTPS requests. For example, you might:

call the API from a serverless edge function
query Atlas from a mobile application
access test data and log events in a CI/CD workflow
integrate Atlas into a federated API gateway
connect from an environment not currently supported via a MongoDB Driver or Realm SDK

An operation called through an API endpoint will likely take longer than the corresponding MongoDB operation called through a connected MongoDB Driver. For high-load use-cases and latency sensitive applications, we recommend connecting directly to your database with a MongoDB driver. To learn more, visit the MongoDB Drivers documentation.

Base URL

The Data API endpoints in an app share a base URL. The URL uses your App ID to uniquely point to your app and specifies which version of the Data API to call. Each endpoint has a unique URL formed by appending the endpoint's route to your app's base URL.

Globally deployed apps use the following format:

Endpoint Base URL (Global Apps):

https://data.mongodb-api.com/app/<App ID>/endpoint/data/<API Version>

Endpoints in a locally deployed app use a base URL specific to the app's deployment region (e.g. us-east-1.aws):

Endpoint Base URL (Local Apps)

https://<Region>.<Cloud>.data.mongodb-api.com/app/<App ID>/endpoint/data/<API Version>

Set Up the Data API

You can configure the Data API for your app from the App Services UI or by deploying configuration files with App Services CLI:

Click HTTPS Endpoints in the left navigation menu and then select the Data API tab.
Enable the Data API for your app. This generates endpoints that can access any MongoDB data source linked to your app.
Choose an authentication method and enable authentication providers.
Choose a response type.
Save the Data API configuration.
Configure access permissions by defining rules for collections in your linked data sources to allow requests to securely read and write data.
Save and deploy your app.

Pull the latest version of your app.
```
appservices pull --remote="<Your App ID>"
```
Define a Data API configuration file.
https_endpoints/data_api_config.json
```
{
  "disabled": false,
  "versions": ["v1"],
  "can_evaluate": {},
  "return_type": <"JSON" | "EJSON">
}
```
Deploy your app.
```
appservices push
```

Authentication

Data API endpoints run in the context of a specific user, which allows your app to enforce rules and validate document schemas for each request.

By default, endpoints use Application Authentication, which requires each request to include credentials for one of your application users, like an API key or JWT. You can also configure other custom authentication schemes to fit your application's needs.

For examples of how to authenticate requests, see Authenticate Data API Requests.

Application authentication requires users to log in with an authentication provider that you have enabled for your App. Requests can either include an access token granted by the authentication provider or the credentials the user would log in with (e.g. their API key or email and password).

User ID authentication runs all requests as a single, pre-selected application user. This is useful if all requests should have the same permissions regardless of who called the endpoint.

To select the user, specify their User Account ID in your app's Data API configuration.

http_endpoints/data_api_config.json

{
  "run_as_user_id": "628e47baf4c2ac2796fc8a91"
}

Script authentication calls a function to determine which application user a request runs as. You can use this to implement custom authentication and authorization schemes.

The function must return an existing application user's Account ID as a string or { "runAsSystem": true } to run the request as a system user that has full access to MongoDB CRUD and Aggregation APIs and is not affected by any rules, roles, or permissions.

To define the function, specify the source code in your app's Data API configuration.

http_endpoints/data_api_config.json

[
  {
    ...,
    "run_as_user_id_script_source": "exports = () => {return \"628e47baf4c2ac2796fc8a91\"}"
  }
]

Authorization

You can require authenticated users to provide additional authorization information in each request. You define the authorization scheme for all generated Data API endpoints in your Data API configuration.

Endpoints natively support a set of built-in authorization schemes that use a secret string to prove that the request is authorized. You can also define a custom authorization scheme that you can use together with or instead of the built-in schemes.

Built-In Authorization Schemes

Endpoints support the following built-in authorization schemes:

All authenticated users are authorized to call the endpoint. Authenticated requests do not need to include authorization information.

Authenticated users must prove that they are authorized to call the endpoint by including a specific string as the value of the secret query parameter.

You define the string in a secret and reference the secret by name in the endpoint configuration.

http_endpoints/data_api_config.json

[
  {
    ...,
    "verification_method": "SECRET_AS_QUERY_PARAM",
    "secret_name": "secret_verification_string"
  }
]

To learn how to include the secret in a request, see Authorize the Request.

Authenticated users must prove that they are authorized to call the endpoint by including an Endpoint-Signature header that contains a hexadecimal-encoded HMAC SHA-256 hash generated from the request body and a secret string.

You define the string in a secret and reference the secret by name in the endpoint configuration.

To learn how to sign your requests, see Authorize the Request.

Custom Authorization Schemes

You can define a custom authorization expression to determine if an incoming authenticated request is allowed to run. The expression is evaluated for each request and must evaluate to true to allow the request. If the expression evaluates to false, the request is not authorized and fails with an error. Requests that fail authorization are not counted toward your App's billed usage.

Authorization expressions can use variables like %%user to authorize based on the calling user's data or %%request to make decisions based on the specifics of each incoming request.

To define a custom authorization scheme, specify the expression in your app's Data API configuration:

http_endpoints/data_api_config.json

{
  ...,
  "can_evaluate": {
    "%%request.requestHeaders.x-secret-key": "my-secret"
  }
}

Response Type

Endpoints can return data in one of two data formats, either JSON or EJSON.

By default, endpoints return JSON, which is a standard data format that is widely supported modern langauges and platforms. However, JSON cannot represent every data type that you can store in MongoDB and loses type information for some data types.

You can also configure endpoints to return EJSON, which uses structured JSON objects to fully represent the types that MongoDB supports. This preserves type information in responses but requires that your application understands how to parse and use EJSON.

Tip

The official MongoDB drivers include methods for working with EJSON. You can also download a standalone parser like bson on npm.

https_endpoints/data_api_config.json

{
   "return_type": "JSON"
}

https_endpoints/data_api_config.json

{
   "return_type": "EJSON"
}

Access Permissions

The Data API uses your app's data access rules to determine if a user can read and write data. To allow Data API requests to access a specific collection, you must first define rules for the collection.

You can also set up an IP Access List for additional security.

API Versions

The Data API uses a built-in versioning scheme to upgrade endpoints over time while maintaining backwards compatibility. Incoming requests can specify which version of an endpoint to use in the request URL and the Data API can serve any version that you have enabled.

You must enable a new version before users can call endpoints with that version. You can always enable the most recent Data API version. However, you cannot enable an older version after a newer version has been released.

The following versions are currently supported:

beta
v1

Call a Data API Endpoint

You can call a Data API endpoint from any standard HTTP client. Each request can include configuration headers and arguments in the request body.

HTTP/1.1 or greater is required when making requests.

Choose an API Version

Data API requests specify which version of the API to use in the request URL. A request can specify any version that is enabled for your app.

https://data.mongodb-api.com/app/<App ID>/endpoint/data/<API Version>

Specify the Request Data Format

Data API requests must include a Content-Type header to specify the data format used in the request body.

Use Content-Type: application/json to represent standard JSON types in a Data API request body.
Use Content-Type: application/ejson to represent standard JSON types and additional EJSON types in a Data API request body.

curl -X GET \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/insertOne \
  -H 'apiKey: <API Key>' \
  -H 'Content-Type: application/ejson' \
  -H 'Accept: application/ejson' \
  --data-raw '{
      "dataSource": "mongodb-atlas",
      "database": "learn-data-api",
      "collection": "hello",
      "document": {
        "_id": { "$oid": "629971c0d71aad65bd59c595" },
        "greeting": "Hello, EJSON!",
        "date": { "$date": { "$numberLong": "1654589430998" } }
      }
  }'

{ "insertedId": { "$oid": "629971c0d71aad65bd59c595" } }

curl -X POST \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/updateOne \
  -H 'apiKey: <API Key>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
     "dataSource": "mongodb-atlas",
     "database": "learn-data-api",
     "collection": "hello",
     "filter": { "greeting": "Hello, world!" },
     "update": {
         "$set": { "greeting": "Hello, universe!" }
     }
  }'

Choose a Response Data Format

A request can include an Accept header to request a specific data format for the response body, either JSON or EJSON. If a request does not include a valid Accept header, the response uses the data format specified in your Data API configuration.

curl -X GET \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne \
  -H 'apiKey: <API Key>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/ejson' \
  --data-raw '{
     "dataSource": "mongodb-atlas",
     "database": "learn-data-api",
     "collection": "hello",
     "projection": { "greeting": 1, "date": 1 }
  }'

{
  "_id": { "$oid": "629971c0d71aad65bd59c545"},
  "greeting": "Hello, Leafie!",
  "date": { "$date": { "$numberLong": "1654589430998" } }
}

curl -X POST \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne \
  -H 'apiKey: <API Key>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{
     "dataSource": "mongodb-atlas",
     "database": "learn-data-api",
     "collection": "hello",
     "projection": { "greeting": 1, "date": 1 }
  }'

{
  "_id": "629971c0d71aad65bd59c545",
  "greeting": "Hello, Leafie!",
  "date": "2022-06-07T08:10:30.998Z"
}

Authenticate the Request

If an endpoint is configured to use Application Authentication then you must include a valid user access token or login credentials with every request.

In general, bearer authentication with an access token has higher throughput and is more secure than credential headers. Use an access token instead of credential headers when possible. The token lets you run multiple requests without re-authenticating the user. It also lets you send requests from a web browser that enforces CORS.

To use an access token, first authenticate the user through an App Services authentication provider. Then, get the access token returned from App Services and include it in the request's Authorization header using a Bearer token scheme. For more information on how to acquire and use an access token, see Bearer Token Authentication.

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne" \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "sample_mflix",
    "collection": "movies",
    "filter": {
      "title": "The Matrix"
    }
  }'

Alternatively, you can include valid login credentials for the user in the request headers.

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne" \
  -X POST \
  -H "Accept: application/json" \
  -H "email: bob@example" \
  -H "password: Pa55w0rd!" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "sample_mflix",
    "collection": "movies",
    "filter": {
      "title": "The Matrix"
    }
  }'

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne" \
  -X POST \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "sample_mflix",
    "collection": "movies",
    "filter": {
      "title": "The Matrix"
    }
  }'

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne" \
  -X POST \
  -H "Accept: application/json" \
  -H "jwtTokenString: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJteWFwcC1hYmNkZSIsInN1YiI6IjEyMzQ1Njc4OTAiLCJuYW1lIjoiSm9obiBEb2UiLCJleHAiOjIxNDU5MTY4MDB9.E4fSNtYc0t5XCTv3S8W89P9PKLftC4POLRZdN2zOICI" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "sample_mflix",
    "collection": "movies",
    "filter": {
      "title": "The Matrix"
    }
  }'

Important

Don't Use API Keys in User-Facing Clients

If you're authenticating from a browser or another user-facing client application, avoid using an API key to log in. Instead, use another authentication provider that takes user-provided credentials. Never store API keys or other sensitive credentials locally.

Authorize the Request

Depending on your Data API authorization configuration, your requests may need to include additional authorization information.

All authenticated users are authorized to call the endpoint. Authenticated requests do not need to include authorization information.

Authenticated users must prove that they are authorized to call the endpoint by including the endpoint's secret string as the value of the secret query parameter.

Example

The following curl request uses secret query parameter validation with the secret string "12345":

curl -X POST \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne?secret=12345 \
  -H "Content-Type: application/json" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "tasks",
    "filter": { "text": "Do the dishes" }
  }'

Endpoint-Signature: sha256=<hex encoded hash>

You could use the following function to generate the payload signature:

/**
 * Generate an HMAC request signature.
 * @param {string} secret - The secret validation string, e.g. "12345"
 * @param {object} body - The endpoint request body e.g. { "message": "MESSAGE" }
 * @returns {string} The HMAC SHA-256 request signature in hex format.
 */
exports = function signEndpointRequest(secret, body) {
  const payload = EJSON.stringify(body);
  return utils.crypto.hmac(payload, secret, "sha256", "hex");
};

Example

The following curl includes a payload signature header signed with the secret value 12345:

curl -X POST \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne \
  -H "Content-Type: application/json" \
  -H "Endpoint-Signature: sha256=769cd86855787f476afc8b0d2cf9837ab0318181fca42f45f34b6dffd086dfc7" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "tasks",
    "filter": { "text": "Do the dishes" }
  }'

Back

Data API

Custom HTTPS Endpoints

Data API Endpoints.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

Note

When to Use the Data API

Base URL

Set Up the Data API

Authentication

Authorization

Built-In Authorization Schemes

Custom Authorization Schemes

Response Type

Tip

Access Permissions

API Versions

Call a Data API Endpoint

Choose an API Version

Specify the Request Data Format

Choose a Response Data Format

Authenticate the Request

Important

Don't Use API Keys in User-Facing Clients

Authorize the Request

Example

Example

Data API Endpoints