Docs Menu
Docs Home
/
MongoDB Atlas
/
Atlas App Services
/
Reference
/
GraphQL API [Deprecated]

Authenticate GraphQL Requests

On this page

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

Overview

The GraphQL API requires that incoming requests include authentication information for the user making the request. This lets the API enforce rules and validate document schemas for each operation.

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, the request must use Bearer Authentication with a valid user access token. If the token is invalid, the request fails.

  2. If the Authorization header is not present, 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.

Bearer Authentication

The GraphQL API supports Bearer Authentication, which lets you authenticate a request by including a valid user access token in the 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 -X POST 'https://services.cloud.mongodb.com/api/client/v2.0/app/<AppID>/graphql' \
   --header 'Authorization: Bearer <AccessToken>' \
   --header 'Content-Type: application/json' \
   --data-raw '{
     "query": "query AllMovies {\n  movies {\n    title\n    year\n  }\n}"
   }'

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.

Credential Headers

You can authenticate a GraphQL 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 a GraphQL 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 GraphQL requests from a browser, use Bearer Authentication.

Email/Password

To authenticate a GraphQL request as an email/password user, include the user's credentials in the request's email and password headers.

curl -X POST 'https://services.cloud.mongodb.com/api/client/v2.0/app/<AppID>/graphql' \
   --header 'email: <EmailAddress>' \
   --header 'password: <Password>' \
   --header 'Content-Type: application/json' \
   --data-raw '{
     "query": "query AllMovies {\n  movies {\n    title\n    year\n  }\n}"
   }'

API Key

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

curl -X POST 'https://services.cloud.mongodb.com/api/client/v2.0/app/<AppID>/graphql' \
   --header 'apiKey: <APIKey>' \
   --header 'Content-Type: application/json' \
   --data-raw '{
     "query": "query AllMovies {\n  movies {\n    title\n    year\n  }\n}"
   }'

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.

Custom JWT

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

curl -X POST 'https://services.cloud.mongodb.com/api/client/v2.0/app/<AppID>/graphql' \
   --header 'jwtTokenString: <JWT>' \
   --header 'Content-Type: application/json' \
   --data-raw '{
     "query": "query AllMovies {\n  movies {\n    title\n    year\n  }\n}"
   }'

Back

Expose Data in a Collection

Next

GraphQL Types, Resolvers, and Operators