Authenticate Data API Requests

Overview

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.

Bearer Authentication

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.

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.

Credential Headers

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

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