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¶
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¶
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.
Application ID¶
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.
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'
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}'
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'
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¶
/auth/providers
Enumerate available Realm administration authentication providers.
/auth/providers/{provider}/login
Authenticate as a Realm administrator. Use get-/auth/providers to list the available authentication providers.
/auth/profile
Get information about the currently logged in user.
/auth/session
Delete a Realm access token.
/auth/session
Obtain a Realm access token.
/groups/{groupID}/apps/{appID}/services/{serviceId}/commands/build_info
Get information about the underlying Atlas mongod.
API Key APIs¶
/groups/{groupId}/apps/{appId}/api_keys
List API keys associated with a Realm app.
/groups/{groupId}/apps/{appId}/api_keys
Create a new API key.
/groups/{groupId}/apps/{appId}/api_keys/{apiKeyId}
Retrieve information about an API key.
/groups/{groupId}/apps/{appId}/api_keys/{apiKeyId}
Delete an API key.
/groups/{groupId}/apps/{appId}/api_keys/{apiKeyId}/enable
Enable an API key.
/groups/{groupId}/apps/{appId}/api_keys/{apiKeyId}/disable
Disable an API key.
Billing APIs¶
/groups/{groupId}/measurements
List the request, compute, sync, and data transfer usage in a given period for billing purposes.
/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¶
/groups/{groupId}/apps/{appId}/secrets
List Secrets associated with a Realm app.
/groups/{groupId}/apps/{appId}/secrets
Create a new Secret.
/groups/{groupId}/apps/{appId}/secrets/{secretId}
Modify a Secret associated with a Realm app.
/groups/{groupId}/apps/{appId}/secrets/{secretId}
Delete a Secret associated with a Realm app.
Application-level APIs¶
/groups/{groupId}/apps
List all Realm apps within an Atlas project/group.
/groups/{groupId}/apps
Create a new Realm app.
/groups/{groupId}/apps/{appId}
Retrieve an application definition.
/groups/{groupId}/apps/{appId}
Delete an application.
/groups/{groupId}/apps/{appId}/export
Export an application as a zip file.
Auth Provider APIs¶
/groups/{groupId}/apps/{appId}/auth_providers
List authentication providers within a Realm app.
/groups/{groupId}/apps/{appId}/auth_providers
Create an authentication provider.
/groups/{groupId}/apps/{appId}/auth_providers/{providerId}
Retrieve information about one of an application's authentication providers
/groups/{groupId}/apps/{appId}/auth_providers/{providerId}
Delete an authentication provider.
/groups/{groupId}/apps/{appId}/auth_providers/{providerId}
Update an authentication provider.
/groups/{groupId}/apps/{appId}/auth_providers/{providerId}/disable
Disable an authentication provider.
/groups/{groupId}/apps/{appId}/auth_providers/{providerId}/enable
Enable an authentication provider.
Email APIs¶
/groups/{groupId}/apps/{appId}/user_registrations/by_email/{email}/send_confirm
Send a confirmation email.
/groups/{groupId}/apps/{appId}/user_registrations/by_email/{email}/confirm
Confirm a pending user.
/groups/{groupId}/apps/{appId}/user_registrations/by_email/{email}/run_confirm
Re-runs a pending user's confirmation workflow.
Functions APIs¶
/groups/{groupId}/apps/{appId}/debug/execute_function
Execute a function for testing.
/groups/{groupId}/apps/{appId}/debug/execute_function_source
Execute a function's source code for testing.
/groups/{groupId}/apps/{appId}/functions
List functions.
/groups/{groupId}/apps/{appId}/functions
Create a new function.
/groups/{groupId}/apps/{appId}/functions/{functionId}
Retrieve a function.
/groups/{groupId}/apps/{appId}/functions/{functionId}
Delete a function.
/groups/{groupId}/apps/{appId}/functions/{functionId}
Update a function.
Logging APIs¶
/groups/{groupId}/apps/{appId}/logs
Retrieve MongoDB Realm logs.
Notifications APIs¶
/groups/{groupId}/apps/{appId}/push/notifications
List push notifications.
/groups/{groupId}/apps/{appId}/push/notifications
Create a push notification.
/groups/{groupId}/apps/{appId}/push/notifications/{messageId}
Retrieve a push notification message.
/groups/{groupId}/apps/{appId}/push/notifications/{messageId}
Delete a push notification message.
/groups/{groupId}/apps/{appId}/push/notifications/{messageId}
Update a push notification message.
/groups/{groupId}/apps/{appId}/push/notifications/{messageId}/type
Set a push notification's type.
/groups/{groupId}/apps/{appId}/push/notifications/{messageId}/send
Send a push notification.
Rules APIs¶
/groups/{groupId}/apps/{appId}/services/{serviceId}/rules
List rules.
/groups/{groupId}/apps/{appId}/services/{serviceId}/rules
Create a rule.
/groups/{groupId}/apps/{appId}/services/{serviceId}/rules/{ruleId}
Retrieve a rule.
/groups/{groupId}/apps/{appId}/services/{serviceId}/rules/{ruleId}
Delete a rule.
/groups/{groupId}/apps/{appId}/services/{serviceId}/rules/{ruleId}
Update a rule.
Security APIs¶
/groups/{groupId}/apps/{appId}/security/allowed_request_origins
List the allowed HTTP origins from which MongoDB Realm should allow requests.
/groups/{groupId}/apps/{appId}/security/allowed_request_origins
Set the allowed HTTP origins from which MongoDB Realm should allow requests.
Services APIs¶
/groups/{groupId}/apps/{appId}/services
List all services within an application.
/groups/{groupId}/apps/{appId}/services
Create a service.
/groups/{groupId}/apps/{appId}/services/{serviceId}
Retrieve a service.
/groups/{groupId}/apps/{appId}/services/{serviceId}
Delete a service.
/groups/{groupId}/apps/{appId}/services/{serviceId}
Update a service.
/groups/{groupId}/apps/{appId}/services/{serviceId}/commands/{commandName}
Run a command associated with a service.
/groups/{groupId}/apps/{appId}/services/{serviceId}/config
Retrieve a service's configuration.
/groups/{groupId}/apps/{appId}/services/{serviceId}/config
Update a service's configuration.
/groups/{groupId}/apps/{appId}/services/{serviceId}/rules
List rules.
/groups/{groupId}/apps/{appId}/services/{serviceId}/rules
Create a rule.
/groups/{groupId}/apps/{appId}/services/{serviceId}/rules/{ruleId}
Retrieve a rule.
/groups/{groupId}/apps/{appId}/services/{serviceId}/rules/{ruleId}
Delete a rule.
/groups/{groupId}/apps/{appId}/services/{serviceId}/rules/{ruleId}
Update a rule.
/groups/{groupId}/apps/{appId}/services/{serviceId}/commands/generate_schema
Sample a subset of documents in a collection to generate a JSON schema.
/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks
List webhooks.
/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks
Create a webhook.
/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks/{incomingWebhookId}
Retrieve a webhook.
/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks/{incomingWebhookId}
Delete a webhook.
/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks/{incomingWebhookId}
Update a webhook.
Sync APIs¶
/groups/{groupId}/apps/{appId}/sync/data
Get sync information for a specific linked MongoDB cluster.
Users APIs¶
/groups/{groupId}/apps/{appId}/users
List users.
/groups/{groupId}/apps/{appId}/users
Create a user.
/groups/{groupId}/apps/{appId}/users/{uid}
Retrieve a user.
/groups/{groupId}/apps/{appId}/users/{uid}
Delete a user.
/groups/{groupId}/apps/{appId}/users/{uid}/devices
List a user's devices.
/groups/{groupId}/apps/{appId}/users/{uid}/logout
Revoke all of a user's sessions.
/groups/{groupId}/apps/{appId}/users/{uid}/enable
Enable a user.
/groups/{groupId}/apps/{appId}/users/{uid}/disable
Disable a user.
/groups/{groupId}/apps/{appId}/user_registrations/by_email/{email}
Delete a pending user.
Values APIs¶
/groups/{groupId}/apps/{appId}/values
List all values defined in an application.
/groups/{groupId}/apps/{appId}/values
Define a Value in an application.
/groups/{groupId}/apps/{appId}/values/{valueId}
Retrieve a value definition from an application.
/groups/{groupId}/apps/{appId}/values/{valueId}
Delete a value defined in an application.
/groups/{groupId}/apps/{appId}/values/{valueId}
Update a value definition in an application.
Incoming Webhook APIs¶
/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks
List webhooks.
/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks
Create a webhook.
/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks/{incomingWebhookId}
Retrieve a webhook.
/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks/{incomingWebhookId}
Delete a webhook.
/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks/{incomingWebhookId}
Update a webhook.
Event Trigger APIs¶
/groups/{groupId}/apps/{appId}/triggers
Create a trigger.
/groups/{groupId}/apps/{appId}/triggers
List all triggers.
/groups/{groupId}/apps/{appId}/triggers/{triggerId}
Update a trigger.
/groups/{groupId}/apps/{appId}/triggers/{triggerId}
Retrieve the configuration for a specific trigger.
/groups/{groupId}/apps/{appId}/triggers/{triggerId}
Delete a trigger.
/groups/{groupId}/apps/{appId}/triggers/{triggerId}/resume
Resume a suspended trigger.
Static File Hosting APIs¶
/groups/{groupId}/apps/{appId}/hosting/assets
List all hosted assets.
/groups/{groupId}/apps/{appId}/hosting/assets
Move or copy a hosted asset to a new resource path.
/groups/{groupId}/apps/{appId}/hosting/assets/asset
Retrieve metadata for a specific hosted asset
/groups/{groupId}/apps/{appId}/hosting/assets/asset
Upload or replace an asset at a specific resource path.
/groups/{groupId}/apps/{appId}/hosting/assets/asset
Update the metadata attributes of a hosted asset at a specific resource path.
Application Deployment APIs¶
/groups/{groupId}/apps/{appId}/deployments
Return the 100 most recent application deployments.
/groups/{groupId}/apps/{appId}/drafts
Return the current application deployment draft, if applicable.
/groups/{groupId}/apps/{appId}/drafts
Create a new application deployment draft, if none exists.
/groups/{groupId}/apps/{appId}/drafts/{draftId}
Discard the specified application deployment draft.
/groups/{groupId}/apps/{appId}/drafts/{draftId}/deployment
Deploy the specified application deployment draft.
/groups/{groupId}/apps/{appId}/drafts/{draftId}/diff
Return a diff between the currently deployed application and the specified draft.
Dependency APIs¶
/dependencies
List external dependencies uploaded to the Realm app.