Data API Endpoints

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.

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.

{
  ...,
  "can_evaluate": {
    "%%request.headers.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.

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

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.

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.

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.

Authorize the Request

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