Navigation

Connection Strings

On this page

Overview

To connect to Stitch 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.

URL Encoding

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

Stitch connection strings have the following form:

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

Connection String Components

Credentials

All Stitch 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:

Format <email>:<password>
Fields
<email> The user’s registered email address.
<password> The user’s password.
Example
copy 
joe.schmoe@company.com:SuperSecretPassword123
Format _:<apiKey>
Fields
<apiKey> An active application API Key.
Example
copy 
_:tOSJwYhLLam1qTAwP8rZ5M9BiHfn69w5xrya52dYeOv1PdTlD68i8gKOaN0Wy24z
Format _:<customAuthToken>
Fields
<customAuthToken> A custom authentication JSON Web Token.
Example
copy 
_:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
  eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
  SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Parameters

Stitch 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.

Stitch 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:

copy 
<app id>:<service>:<provider>
<app id> The App ID of the Stitch application.
<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

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.