Authenticate HTTP Client Requests

On this page

Overview

Authenticate Requests with a Client API Access Token
Get a Client API Access Token
Refresh a Client API Access Token
Verify a Client Access Token
Responses

Overview

MongoDB Realm enforces non-sync rules and sync rules for all client operations. This means that requests must be made by a logged in user of your Realm app.

Authenticate Requests with a Client API Access Token

To authenticate a GraphQL request as an arbitrary logged in user from any provider, include a valid user access token as a bearer token in the request's Authorization header.

Example

The following request demonstrates how to include an access token for a user with each request. Replace <Access Token> with the access_token value that you want to use.

curl --location --request POST 'https://realm.mongodb.com/api/client/v2.0/app/<yourappid-abcde>/graphql' \
   --header 'Authorization: Bearer <Access Token>' \
   --header 'Content-Type: application/json' \
   --data-raw '{"query":"query AllMovies {\n  movies {\n    title\n    year\n  }\n}"}'

Get a Client API Access Token

To get an access token, you need to authenticate with the realm Client HTTP API using the user's login credentials. The Client API authentication endpoints accept valid user credentials in the body of a POST request and use the following URL form:

https://<hostname>/api/client/v2.0/app/<yourappid>/auth/providers/<provider-type>/login

If your app is deployed globally, the <hostname> is realm.mongodb.com. Otherwise, you need to find your hostname by issuing the following request:

curl --location --request GET \
   'https://realm.mongodb.com/api/client/v2.0/app/<APP NAME>/location' \
   --header 'Content-Type: application/json' \
   --data-raw '{
      "key": <API KEY>
   }'

The hostname is in the response:

{ "deployment_model":"LOCAL",
   "location":"US-VA",
   "hostname":"https://us-east-1.aws.realm.mongodb.com",
   "ws_hostname":"wss://ws.us-east-1.aws.realm.mongodb.com"
}

Example

The following request authenticates a realm user with the client API. The request body specifies the user's login credentials.

The authentication request is successful, so the response body includes access_token and refresh_token values for the user. Each of these values is a JSON web token string that identifies the authenticated user and authorizes requests on their behalf.

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1Nzg5NjY1MTYsImlhdCI6MTU3ODk2NDcxNiwiaXNzIjoiNWUxZDE2ZWM4YWM5M2QzMGFjNDg0ZTk0Iiwic3RpdGNoX2RldklkIjoiMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwIiwic3RpdGNoX2RvbWFpbklkIjoiNWRkODFiYmU3NTFhYzk2ZDM3NmI1Mjg1Iiwic3ViIjoiNWUxM2E0MWUxYjM4ZDM1ODQzMGVkMWYzIiwidHlwIjoiYWNjZXNzIn0.WnWJM01meRDZRVIPr7tXqHcXSgrz0refMrpx7bMVgeQ",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1ODQxNDg3MTYsImlhdCI6MTU3ODk2NDcxNiwic3RpdGNoX2RhdGEiOm51bGwsInN0aXRjaF9kZXZJZCI6IjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMCIsInN0aXRjaF9kb21haW5JZCI6IjVkZDgxYmJlNzUxYWM5NmQzNzZiNTI4NSIsInN0aXRjaF9pZCI6IjVlMWQxNmVjOGFjOTNkMzBhYzQ4NGU5NCIsInN0aXRjaF9pZGVudCI6eyJpZCI6IjVlMTNhNDFlMWIzOGQzNTg0MzBlZDFmMiIsInByb3ZpZGVyX3R5cGUiOiJsb2NhbC11c2VycGFzcyIsInByb3ZpZGVyX2lkIjoiNWUxM2E0MDUxYjM4ZDM1ODQzMGVkMWI3In0sInN1YiI6IjVlMTNhNDFlMWIzOGQzNTg0MzBlZDFmMyIsInR5cCI6InJlZnJlc2gifQ.fqr19MaUykKqi8C8csJUUzNe9jQOucPbtcc0soWgc5k"
}

Refresh a Client API Access Token

Access tokens expire 30 minutes after MongoDB Realm grants them. When an access token expires, you can either request another access token using the user's credentials or use the refresh token to request a new access token with including the user's credentials.

The Client API session refresh endpoint accepts a POST request that includes the refresh token in the Authorization header and uses the following URL:

https://realm.mongodb.com/api/client/v2.0/auth/session

Example

The following request demonstrates how to use a refresh token to get a new, valid access token. Replace <Refresh Token> with the refresh_token value for the access token that you want to refresh.

curl --location --request POST 'https://realm.mongodb.com/api/client/v2.0/auth/session' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <Refresh Token>'

Verify a Client Access Token

If you want to verify that a client access token is valid, you can do so using the verify access token endpoint in the administration API.

This endpoint accepts a POST request that includes these details:

the client access token you got using one of the above methods for the payload
an Admin API access token Authorization header
the {groupId} and {appId} for your backend Realm app

With this information, call this API endpoint to verify that the client access token is valid:

https://realm.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/users/verify_token

Important

Do Not Access the Admin API Directly from Client Applications

Because this endpoint requires admin API access, implementing this is best done as a backend service behind an authorization layer - not directly in the client app.

Example

The following request demonstrates how to use the Admin API endpoint to verify that a user's client access token is valid. Replace <API Access Token> with the access_token value you get after authenticating with the Admin API, and <Client Access Token> with the client access token you got using one of the above methods. In the URL, replace {groupId} and {appId} with the values for your Realm app.

curl --request POST \
  --url https://realm.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/users/verify_token \
  --header 'Authorization: Bearer <API Access Token>' \
  --header 'Content-Type: application/json' \
  --data '{ "token": "<Client Access Token>" }'

Responses

Valid access token: If you get a 200 OK with a response that contains the following fields, the <Client Access Token> is valid:

{
  "sub": "60367b71e07e1fa6f55af328",
  "exp": 1614185081,
  "iat": 1614183281,
  "iss": "60367b71e07e1fa6f55af32a",
  "domain_id": "6025a0d127065da7ff49d260",
  "device_id": "000000000000000000000000"
}

Expired Client Access Token: If the <Client Access Token> has expired, you'll get a 200 OK but the response will return token expired.

{
  "token expired"
}

Invalid Client Access Token: If the <Client Access Token> is not valid, you'll get a 400 Bad Request that contains additional details about the error.

{
  "error": "token contains an invalid number of segments"
}

Expired API Access Token: If the <API Access Token> has expired, you'll get a 401 Unauthorized containing this response:

{
  "error": "invalid session",
  "error_code": "InvalidSession"
}

Welcome to the MongoDB Realm Docs →