Navigation

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.

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>
Info With Circle IconCreated with Sketch.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.

To find your Project ID, go to your Atlas administration console, click Settings in the left navigation menu, and look under the Project ID heading.

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

This request has the following format, referencing the access_token described in API Authentication:

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. The _id field contains the Application ID.

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.

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

1

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'
Important With Circle IconCreated with Sketch.Important
One Draft Per User

Each user can only create a single draft at a time, either through the UI or the Admin API. If you already have an existing draft, you can discard the changes associated with it by sending a DELETE request to the draft's endpoint:

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

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.

3

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'
https://realm.mongodb.com/api/admin/v3.0

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

GET
/​auth/​providers

Enumerate available Realm administration authentication providers.

POST
/​auth/​providers/​{provider}/​login

Authenticate as a Realm administrator. Use get-/auth/providers to list the available 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.

GET
/​groups/​{groupID}/​apps/​{appID}/​services/​{serviceId}/​commands/​build_info

Get information about the underlying Atlas mongod.

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.

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.

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.

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.

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

List authentication providers within a Realm app.

POST
/​groups/​{groupId}/​apps/​{appId}/​auth_providers
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}
PATCH
/​groups/​{groupId}/​apps/​{appId}/​auth_providers/​{providerId}
PUT
/​groups/​{groupId}/​apps/​{appId}/​auth_providers/​{providerId}/​disable
PUT
/​groups/​{groupId}/​apps/​{appId}/​auth_providers/​{providerId}/​enable
POST
/​groups/​{groupId}/​apps/​{appId}/​user_registrations/​by_email/​{email}/​send_confirm
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.

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.

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

Retrieve MongoDB Realm logs.

GET
/​groups/​{groupId}/​apps/​{appId}/​push/​notifications
POST
/​groups/​{groupId}/​apps/​{appId}/​push/​notifications
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
POST
/​groups/​{groupId}/​apps/​{appId}/​push/​notifications/​{messageId}/​send
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.

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}/​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}/​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.

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

Get sync information for a specific linked MongoDB cluster.

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

List users.

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

Create a user.

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.

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.

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.

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.

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.

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.

GET
/​dependencies

List external dependencies uploaded to the Realm app.

Give Feedback