Realm Administration API¶

MongoDB Realm provides an API for programmatically performing administrative tasks outside of the Realm UI. This includes tasks such as modifying authentication providers, creating rules, and defining functions. Client applications should not use the admin API. Instead, use one of the Client SDKs for tasks like authenticating users, calling functions, and interacting with services.

API Authentication¶

Every request to the Realm Admin API must include a valid and current authorization token from the MongoDB Cloud API as a bearer token in the Authorization header. You will need a valid programmatic API key for MongoDB Atlas to get a token.

Once you have an API key pair, call the authentication endpoint:

curl --request POST \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"username": "<Public API Key>", "apiKey": "<Private API Key>"}' \
  https://realm.mongodb.com/api/admin/v3.0/auth/providers/mongodb-cloud/login

If authentication succeeds, MongoDB Realm returns an access token as part of the JSON response document:

{
  "access_token": "<access_token>",
  "refresh_token": "<refresh_token>",
  "user_id": "<user_id>",
  "device_id": "<device_id>"
}

The access_token represents a limited-time authorization to interact with the Admin API. To authenticate a request, include the token in a Bearer token Authorization header.

Authorization: Bearer <access_token>

Project & Application IDs¶

Note

The terms Project ID and Group ID are interchangeable.

Realm APIs frequently require two parameters: your Atlas Project/Group ID, and your Realm Application ID.

Project ID¶

You can find your Project ID from your MongoDB Atlas Dashboard.

Tip

Application ID¶

To find an Application ID, make a request to the Realm GET /groups/{groupid}/apps API endpoint.

This request has the following format, referencing the access_token and the Group ID:

curl --request GET \
  --header 'Authorization: Bearer <access_token>' \
  https://realm.mongodb.com/api/admin/v3.0/groups/{groupId}/apps

This will return a list of objects describing each Realm app in the provided group. For Admin API requests, your Application ID is the ObjectId value in the _id field, not the client_app_id.

Example

[
  {
      "_id": "5997529e46224c6e42gb6dd9",
      "group_id": "57879f6cc4b32dbe440bb8c5",
      "domain_id": "5886619e46124e4c42fb5dd8",
      "client_app_id": "myapp-abcde",
      "name": "myapp",
      "location": "US-VA",
      "deployment_model": "GLOBAL",
      "last_used": 1615153544,
      "last_modified": 0,
      "product": "standard",
      "environment": ""
  }
]

Example¶

Pagination with the Logging API¶

The Logging endpoint returns up to 100 log entries per page. If the query matches more than 100 entries, the result will be paginated. Such a result will contain two pieces of information that you will need to request the next page of entries for the same query: the nextEndDate and nextSkip fields.

Paginated results always contain the nextEndDate field. A paginated result will also contain the nextSkip field if the timestamp of the first entry on the next page is identical to the timestamp of the last entry on the current page.

To request the first page of up to 100 log entries, use the endpoint as usual:

curl --request GET \
  --header 'Authorization: Bearer <access_token>' \
  'https://realm.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/logs'

To request the next page of up to 100 log entries, pass the values of nextEndDate and nextSkip as the end_date and skip parameters, respectively:

curl --request GET \
  --header 'Authorization: Bearer <access_token>' \
  'https://realm.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/logs?end_date={nextEndDate of previous response}&skip={nextSkip of previous response}'

Repeat this step to get more pages until the response does not have a nextEndDate field. This signifies that you have reached the last page.

For more information, see GET /groups/{groupId}/apps/{appId}/logs.

Draft and Deploy a Group of Changes¶

You can deploy a group of application changes together by creating and deploying a draft. To create and deploy a set of draft changes:

Create a New Draft¶

A draft represents a group of application changes that you can deploy or discard as a single unit. To create a draft, send a POST request to the drafts endpoint:

curl --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <access_token>' \
  'https://realm.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/drafts'

Tip

Make Changes to Your Application¶

Once you've created a draft, make all of the changes that you want to include in the draft. Realm adds any application changes that you make to the draft so that you can deploy them together.

Deploy the Draft¶

After you've made all the changes that you want to include in the deployment, deploy the draft by sending a POST request to that draft's deployment endpoint:

curl --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <access_token>' \
  'https://realm.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/drafts/{draftId}/deployment'

Important

Draft Conflicts

If you deploy changes through the API but have conflicting changes in a draft in the UI, your UI draft will become invalid and you will not be able to deploy it. You can download your UI draft by reviewing the draft in the Deployment page. You can use the download to deploy your changes in the realm-cli or as a reference as you reapply changes in the UI.

Asset Metadata Document Example¶

Asset metadata documents describe hosted asset files.

{
   "path": "<Asset Resource Path>",
   "hash": "<Asset MD5 Checksum Hash>",
   "size": <File size in bytes>,
   "attrs": [
      {
         "name": "<Metadata Attribute Name>",
         "value": "<Metadata Attribute Value>",
      }
   ]
}

Resources¶

Base URL¶

https://realm.mongodb.com/api/admin/v3.0

The root API resource and starting point for the Realm API.

Realm Administrator APIs¶

GET

/auth/providers

Enumerate available Realm administration authentication providers.

GET

/auth/profile

Get information about the currently logged in user.

DELETE

/auth/session

Delete a Realm access token.

POST

/auth/session

Obtain a Realm access token.

API Key APIs¶

GET

/groups/{groupId}/apps/{appId}/api_keys

List API keys associated with a Realm app.

POST

/groups/{groupId}/apps/{appId}/api_keys

Create a new API key.

GET

/groups/{groupId}/apps/{appId}/api_keys/{apiKeyId}

Retrieve information about an API key.

DELETE

/groups/{groupId}/apps/{appId}/api_keys/{apiKeyId}

Delete an API key.

PUT

/groups/{groupId}/apps/{appId}/api_keys/{apiKeyId}/enable

Enable an API key.

PUT

/groups/{groupId}/apps/{appId}/api_keys/{apiKeyId}/disable

Disable an API key.

Billing APIs¶

GET

/groups/{groupId}/measurements

List the request, compute, sync, and data transfer usage in a given period for billing purposes.

GET

/groups/{groupId}/apps/{appId}/measurements/

List the request, compute, sync, data transfer, and memory usage of a specific app in a given period for billing purposes.

Secrets APIs¶

GET

/groups/{groupId}/apps/{appId}/secrets

List secrets associated with a Realm app.

POST

/groups/{groupId}/apps/{appId}/secrets

Create a new Secret.

PUT

/groups/{groupId}/apps/{appId}/secrets/{secretId}

Modify a Secret associated with a Realm app.

DELETE

/groups/{groupId}/apps/{appId}/secrets/{secretId}

Delete a Secret associated with a Realm app.

Application-level APIs¶

GET

/groups/{groupId}/apps

List all Realm apps within an Atlas project/group.

POST

/groups/{groupId}/apps

Create a new Realm app.

GET

/groups/{groupId}/apps/{appId}

Retrieve an application definition.

DELETE

/groups/{groupId}/apps/{appId}

Delete an application.

GET

/groups/{groupId}/apps/{appId}/export

Export an application as a zip file.

Auth Provider APIs¶

GET

/groups/{groupId}/apps/{appId}/auth_providers

List authentication providers within a Realm app.

POST

/groups/{groupId}/apps/{appId}/auth_providers

Create an authentication provider.

GET

/groups/{groupId}/apps/{appId}/auth_providers/{providerId}

Retrieve information about one of an application's authentication providers

DELETE

/groups/{groupId}/apps/{appId}/auth_providers/{providerId}

Delete an authentication provider.

PATCH

/groups/{groupId}/apps/{appId}/auth_providers/{providerId}

Update an authentication provider.

PUT

/groups/{groupId}/apps/{appId}/auth_providers/{providerId}/disable

Disable an authentication provider.

PUT

/groups/{groupId}/apps/{appId}/auth_providers/{providerId}/enable

Enable an authentication provider.

Email APIs¶

POST

/groups/{groupId}/apps/{appId}/user_registrations/by_email/{email}/send_confirm

Send a confirmation email.

POST

/groups/{groupId}/apps/{appId}/user_registrations/by_email/{email}/confirm

Confirm a pending user.

POST

/groups/{groupId}/apps/{appId}/user_registrations/by_email/{email}/run_confirm

Re-runs a pending user's confirmation workflow.

Functions APIs¶

POST

/groups/{groupId}/apps/{appId}/debug/execute_function

Execute a function for testing.

POST

/groups/{groupId}/apps/{appId}/debug/execute_function_source

Execute a function's source code for testing.

GET

/groups/{groupId}/apps/{appId}/functions

List functions.

POST

/groups/{groupId}/apps/{appId}/functions

Create a new function.

GET

/groups/{groupId}/apps/{appId}/functions/{functionId}

Retrieve a function.

DELETE

/groups/{groupId}/apps/{appId}/functions/{functionId}

Delete a function.

PUT

/groups/{groupId}/apps/{appId}/functions/{functionId}

Update a function.

Logging APIs¶

GET

/groups/{groupId}/apps/{appId}/logs

Retrieve MongoDB Realm logs.

Notifications APIs¶

GET

/groups/{groupId}/apps/{appId}/push/notifications

List push notifications.

POST

/groups/{groupId}/apps/{appId}/push/notifications

Create a push notification.

GET

/groups/{groupId}/apps/{appId}/push/notifications/{messageId}

Retrieve a push notification message.

DELETE

/groups/{groupId}/apps/{appId}/push/notifications/{messageId}

Delete a push notification message.

PUT

/groups/{groupId}/apps/{appId}/push/notifications/{messageId}

Update a push notification message.

PUT

/groups/{groupId}/apps/{appId}/push/notifications/{messageId}/type

Set a push notification's type.

POST

/groups/{groupId}/apps/{appId}/push/notifications/{messageId}/send

Send a push notification.

Rules APIs¶

GET

/groups/{groupId}/apps/{appId}/services/{serviceId}/rules

List rules.

POST

/groups/{groupId}/apps/{appId}/services/{serviceId}/rules

Create a rule.

GET

/groups/{groupId}/apps/{appId}/services/{serviceId}/rules/{ruleId}

Retrieve a rule.

DELETE

/groups/{groupId}/apps/{appId}/services/{serviceId}/rules/{ruleId}

Delete a rule.

PUT

/groups/{groupId}/apps/{appId}/services/{serviceId}/rules/{ruleId}

Update a rule.

Security APIs¶

GET

/groups/{groupId}/apps/{appId}/security/allowed_request_origins

List the allowed HTTP origins from which MongoDB Realm should allow requests.

POST

/groups/{groupId}/apps/{appId}/security/allowed_request_origins

Set the allowed HTTP origins from which MongoDB Realm should allow requests.

GET

/groups/{groupId}/apps/{appId}/security/access_list

List the allowed entries in the Access List of your Realm app.

POST

/groups/{groupId}/apps/{appId}/security/access_list

Create an IP address or CIDR block in the Access List for your Realm app.

PATCH

/groups/{groupId}/apps/{appId}/security/access_list/{ipId}

Modify an IP address or CIDR block in the Access List of your Realm app

DELETE

/groups/{groupId}/apps/{appId}/security/access_list/{ipId}

Delete an IP address or CIDR block from the Access List of your Realm app

Services APIs¶

GET

/groups/{groupId}/apps/{appId}/services

List all services within an application.

POST

/groups/{groupId}/apps/{appId}/services

Create a service.

GET

/groups/{groupId}/apps/{appId}/services/{serviceId}

Retrieve a service.

DELETE

/groups/{groupId}/apps/{appId}/services/{serviceId}

Delete a service.

PATCH

/groups/{groupId}/apps/{appId}/services/{serviceId}

Update a service.

POST

/groups/{groupId}/apps/{appId}/services/{serviceId}/commands/{commandName}

Run a command associated with a service.

GET

/groups/{groupId}/apps/{appId}/services/{serviceId}/commands/build_info

Get information about the underlying Atlas mongod.

GET

/groups/{groupId}/apps/{appId}/services/{serviceId}/config

Retrieve a service's configuration.

PATCH

/groups/{groupId}/apps/{appId}/services/{serviceId}/config

Update a service's configuration.

GET

/groups/{groupId}/apps/{appId}/services/{serviceId}/rules

List rules.

POST

/groups/{groupId}/apps/{appId}/services/{serviceId}/rules

Create a rule.

GET

/groups/{groupId}/apps/{appId}/services/{serviceId}/rules/{ruleId}

Retrieve a rule.

DELETE

/groups/{groupId}/apps/{appId}/services/{serviceId}/rules/{ruleId}

Delete a rule.

PUT

/groups/{groupId}/apps/{appId}/services/{serviceId}/rules/{ruleId}

Update a rule.

POST

/groups/{groupId}/apps/{appId}/services/{serviceId}/commands/generate_schema

Sample a subset of documents in a collection to generate a JSON schema.

GET

/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks

List webhooks.

POST

/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks

Create a webhook.

GET

/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks/{incomingWebhookId}

Retrieve a webhook.

DELETE

/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks/{incomingWebhookId}

Delete a webhook.

PUT

/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks/{incomingWebhookId}

Update a webhook.

Sync APIs¶

GET

/groups/{groupId}/apps/{appId}/sync/data

Get sync information for a specific linked MongoDB cluster.

Users APIs¶

GET

/groups/{groupId}/apps/{appId}/users

List users.

POST

/groups/{groupId}/apps/{appId}/users

Create a user.

POST

/groups/{groupId}/apps/{appId}/users/verify_token

Verify a that a user's client access token is valid.

GET

/groups/{groupId}/apps/{appId}/users/{uid}

Retrieve a user.

DELETE

/groups/{groupId}/apps/{appId}/users/{uid}

Delete a user.

GET

/groups/{groupId}/apps/{appId}/users/{uid}/devices

List a user's devices.

PUT

/groups/{groupId}/apps/{appId}/users/{uid}/logout

Revoke all of a user's sessions.

PUT

/groups/{groupId}/apps/{appId}/users/{uid}/enable

Enable a user.

PUT

/groups/{groupId}/apps/{appId}/users/{uid}/disable

Disable a user.

DELETE

/groups/{groupId}/apps/{appId}/user_registrations/by_email/{email}

Delete a pending user.

Values APIs¶

GET

/groups/{groupId}/apps/{appId}/values

List all values defined in an application.

POST

/groups/{groupId}/apps/{appId}/values

Define a Value in an application.

GET

/groups/{groupId}/apps/{appId}/values/{valueId}

Retrieve a value definition from an application.

DELETE

/groups/{groupId}/apps/{appId}/values/{valueId}

Delete a value defined in an application.

PUT

/groups/{groupId}/apps/{appId}/values/{valueId}

Update a value definition in an application.

Incoming Webhook APIs¶

GET

/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks

List webhooks.

POST

/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks

Create a webhook.

GET

/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks/{incomingWebhookId}

Retrieve a webhook.

DELETE

/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks/{incomingWebhookId}

Delete a webhook.

PUT

/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks/{incomingWebhookId}

Update a webhook.

Event Trigger APIs¶

POST

/groups/{groupId}/apps/{appId}/triggers

Create a trigger.

GET

/groups/{groupId}/apps/{appId}/triggers

List all triggers.

PUT

/groups/{groupId}/apps/{appId}/triggers/{triggerId}

Update a trigger.

GET

/groups/{groupId}/apps/{appId}/triggers/{triggerId}

Retrieve the configuration for a specific trigger.

DELETE

/groups/{groupId}/apps/{appId}/triggers/{triggerId}

Delete a trigger.

PUT

/groups/{groupId}/apps/{appId}/triggers/{triggerId}/resume

Resume a suspended trigger.

Static File Hosting APIs¶

GET

/groups/{groupId}/apps/{appId}/hosting/assets

List all hosted assets.

POST

/groups/{groupId}/apps/{appId}/hosting/assets

Move or copy a hosted asset to a new resource path.

GET

/groups/{groupId}/apps/{appId}/hosting/assets/asset

Retrieve metadata for a specific hosted asset

PUT

/groups/{groupId}/apps/{appId}/hosting/assets/asset

Upload or replace an asset at a specific resource path.

PATCH

/groups/{groupId}/apps/{appId}/hosting/assets/asset

Update the metadata attributes of a hosted asset at a specific resource path.

Application Deployment APIs¶

GET

/groups/{groupId}/apps/{appId}/deployments

Return the 100 most recent application deployments.

GET

/groups/{groupId}/apps/{appId}/drafts

Return the current application deployment draft, if applicable.

POST

/groups/{groupId}/apps/{appId}/drafts

Create a new application deployment draft, if none exists.

DELETE

/groups/{groupId}/apps/{appId}/drafts/{draftId}

Discard the specified application deployment draft.

POST

/groups/{groupId}/apps/{appId}/drafts/{draftId}/deployment

Deploy the specified application deployment draft.

GET

/groups/{groupId}/apps/{appId}/drafts/{draftId}/diff

Return a diff between the currently deployed application and the specified draft.

Dependency APIs¶

GET

/groups/{groupId}/apps/{appId}/dependencies

List external dependencies uploaded to the Realm app.

← Realm Application Security Realm CLI Authenticate With API Token →