Docs Menu

Wire Protocol

On this page

Atlas App Services natively implements a subset of the MongoDB wire protocol, which allows you to connect to an App through one of its linked MongoDB Atlas data sources using standard MongoDB drivers and tools. Clients use a specialized Atlas App Services connection string to connect and send requests. Atlas App Services supports most client features over the wire protocol, including role-based data access rules, functions, and service actions.

This is a good choice for languages that do not currently have a Realm SDK. The examples here are for Python, C++11, and the Mongo Shell. Any MongoDB driver that supports the appName connection string parameter can use the wire protocol to connect to Atlas App Services.

Note

You can use the following tools and drivers to communicate with Atlas App Services using a connection string:

  • Version 4.0+ of the mongo shell.
  • Any MongoDB driver that supports the appName connection string parameter. All official MongoDB drivers support this parameter in their current releases.
Note

Connections to Atlas App Services over the wire protocol have access to the full functionality of the MongoDB Service. However, Atlas App Services does not support all operations and features available in standard tools and clients. For details, see MongoDB Service Limitations.

To connect to Atlas App Services over the wire protocol, you must construct a MongoDB connection string that includes credentials for an application user and an application-specific appName query parameter.

Important
URL Encoding

You must URL encode connection strings before you can use them to connect to Atlas App Services. Connection strings in the Atlas App Services UI are properly encoded by default.

Atlas App Services connection strings have the following form:

mongodb://<credentials>@realm.mongodb.com:27020/?<parameters>

All Atlas App Services operations that you issue over the wire protocol run in the context of a specific application user that you specify in the connection string. The user must be registered with the Email/Password, API Key, or Custom JWT authentication provider.

The contents of connection string credentials depend on the authentication provider with which the user registered:

Atlas App Services requires specific connection string options that identify the application you want to connect to and the authentication provider associated with the credentials that you provide.

Atlas App Services connection strings have the following query parameters:

Parameter
Description
authMechanism
This parameter should always be set to PLAIN.
authSource
This parameter should always be set to $external.
appName

Uniquely identifies the application, MongoDB service, and authentication provider to which you want to connect.

The appName parameter has the following form:

<app id>:<service>:<provider>
<app id>
The App ID of the App.
<service>
The name of the MongoDB Service that you want to connect to. This value will always be mongodb-atlas.
<provider>

The authentication provider for which you provided credentials.

Valid values:

  • local-userpass
  • api-key
  • custom-token

You must enable wire protocol connections for a linked clusters before you can connect to an App Services app with a connection string.

To connect to Atlas App Services over the wire protocol, pass a URL-encoded Atlas App Services connection string when you create a client, just as you would with a regular connection string.

While connected to Atlas App Services over the wire protocol you can use standard MongoDB CRUD operations. Atlas App Services applies role-based data access rules to all queries in the context of the authenticated user specified in the connection string credentials.

You can call functions using the callFunction database command.

Command
Description
Prototype
callFunction
Calls the specified function and returns any result.
{
callFunction: <function name>,
arguments: [<arg1>, <arg2>, ...]
}

You can call service actions using the callServiceFunction database command.

Command
Description
Prototype
callServiceFunction
Calls the specified service action and returns any result.
{
callServiceFunction: <function name>,
service: <service name>,
arguments: [<arg1>, <arg2>, ...]
}

You can get the user object for the authenticated user using the userProfile database command.

Command
Description
Prototype
userProfile
Returns the user object for the authenticated user.
{
userProfile: 1
}
←  Read PreferenceDocument Preimages →
Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.