Docs Menu

Docs HomeAtlas App Services

Authenticate Data API Requests

On this page

  • Overview
  • Bearer Authentication
  • Credential Headers
  • Email/Password
  • API Key
  • Custom JWT

Data API endpoints generally require that incoming requests include authentication information for the user calling the endpoint. This lets the endpoint enforce rules and validate document schemas for each request.

Requests must include authentication data in specific request headers. App Services uses the following process to authenticate a given request:

  1. Check for an Authorization header. If it's present, try to use Bearer Authentication. The header must contain a valid user access token. If the token is invalid, the request fails.

  2. If the Authorization header is not present or does not use the "Bearer" scheme, check for Credential Headers. The headers must contain valid Email/Password, API Key, or Custom JWT credentials for an App user.

Note

You must enable an authentication provider before users can authenticate with it.

The Data API supports Bearer Authentication, which lets you authenticate a request by including a valid user access token in the request's Authorization header. To learn how to get and manage an access token, see Manage User Sessions.

The Authorization header uses the following format:

Authorization: Bearer <AccessToken>

For example, the following request uses Bearer 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"
}
}'

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.

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.

Bearer authentication is useful for:

  • sending requests from a web browser.

  • sending multiple requests without storing user credentials or prompting the user on each request.

  • sending requests from an app that also uses a Realm SDK to authenticate users.

Note

For security reasons, App Services does not return detailed Bearer Authentication errors to the client app. If you are having problems with Bearer Authentication, check the Application Logs.

You can authenticate a Data API request by including the user's login credentials in the request headers. The exact headers to include depend on the authentication provider.

Credential headers are useful for:

  • requests sent from a server-side application

  • requests sent from a command-line tool

  • manual or test requests sent from an HTTPS client like Postman

Important

You cannot use credential headers to authenticate requests sent from a web browser due to Cross-Origin Resource Sharing restrictions. Instead, to authenticate Data API requests from a browser, use Bearer Authentication.

To authenticate a Data API request as an email/password user, include the user's credentials in the request's email and password 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"
}
}'

To authenticate a Data API request with an API Key, include the API key in the request's apiKey header.

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"
}
}'

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.

To authenticate a Data API request as a Custom JWT user, include the JWT string in the request's jwtTokenString header.

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"
}
}'
←  Custom HTTPS EndpointsData API Examples →