Integrate Your App with Atlas App Connections

Key Concepts

Delegated access

Your application acts on behalf of an Atlas user, not as itself. The user's own organization roles and project permissions determine what operations succeed. If the user cannot perform an action, your application cannot perform it on their behalf either.

Organization delegation settings

Each Atlas organization controls whether third-party app connections are allowed. Even when a user authorizes your application, operations against a specific organization succeed only if that organization has third-party app connections enabled. Delegation is disabled by default for existing organizations. Because a user can belong to multiple organizations, a single authorization can succeed for some of the user's organizations and fail for others, depending on each organization's delegation setting.

Proof Key for Code Exchange (PKCE)

A security extension to the OAuth 2.1 Authorization Code flow that protects against authorization code interception attacks. PKCE requires the client to generate a random code_verifier, derive a code_challenge from it, and send the challenge with the authorization request. The client then proves it originated the request by sending the original code_verifier when exchanging the authorization code for tokens.

Flow Overview

click to enlarge

The flow proceeds in three steps:

1. Your application generates a PKCE code verifier and challenge, redirects the user to the Atlas authorization endpoint, and the user approves access on the consent screen.

2. Your application exchanges the authorization code for an access token and a refresh token.

3. Your application uses the access token to call the Atlas Administration API and uses the refresh token to obtain new access tokens before they expire.

Step 1: Authorization Request

Direct the user to the Atlas authorization endpoint (https://cloud.mongodb.com/oauth/authorize) with the following parameters. You control how your application presents this endpoint: a redirect within the existing window, a new browser window, or a pop-up.

Send only the parameters in the preceding table. The authorization endpoint doesn't require a resource parameter, so omit it from the authorization request even though the OAuth 2.1 specification defines one.

The following example breaks the URL across lines for readability. Send it as a single line:

https://cloud.mongodb.com/oauth/authorize
  ?response_type=code
  &client_id=<YOUR_CLIENT_ID>
  &redirect_uri=https://yourapp.example.com/callback
  &code_challenge=<CODE_CHALLENGE>
  &code_challenge_method=S256
  &state=<RANDOM_STATE_VALUE>

Step 2: Token Exchange

Exchange the authorization code for tokens by making a POST request to the Atlas token endpoint:

POST https://authorize.mongodb.com/tokens

Example request:

curl --request POST \
  --url https://authorize.mongodb.com/tokens \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code' \
  --data 'code=<AUTHORIZATION_CODE>' \
  --data 'code_verifier=<CODE_VERIFIER>' \
  --data 'redirect_uri=https://yourapp.example.com/callback' \
  --data 'client_id=<YOUR_CLIENT_ID>' \
  --data 'client_secret=<YOUR_CLIENT_SECRET>'

The response includes:

Step 3: Refreshing Access Tokens

Access tokens are short-lived (currently 10 minutes). Before making Atlas Administration API calls after expiry, exchange your refresh token for a new access token:

curl --request POST \
  --url https://authorize.mongodb.com/tokens \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=refresh_token' \
  --data 'refresh_token=<YOUR_REFRESH_TOKEN>' \
  --data 'client_id=<YOUR_CLIENT_ID>' \
  --data 'client_secret=<YOUR_CLIENT_SECRET>'

The response always returns a new access_token and a new refresh_token. The previous refresh token is immediately invalidated. Always replace both stored values.

Permissions and Organization Delegation Settings

Operations against a specific Atlas organization succeed only when both of the following are true:

• The organization has third-party app connections enabled. Organization owners configure this setting in Organization Settings > App Connections. To learn more about these settings, see Atlas App Connections Overview.

• The authorizing user has the required role for the operation within that organization or project.

If delegation is disabled for an organization after a user has already authorized your application, API calls targeting that organization return a 403 Forbidden response.

A completed authorization doesn't guarantee that Atlas Administration API calls succeed. Atlas evaluates the organization's delegation setting and the user's roles on every request, not once at authorization time, so the OAuth flow and consent screen can complete cleanly while requests still return 403 Forbidden.

Checking Organization Access

Call GET /api/atlas/v2/orgs after authorization to determine which organizations your application can act on. Atlas returns only the organizations that allow third-party app connections, so an empty list means that no organization the user belongs to has enabled them.

An empty list is a setup step, not a failure. Prompt the user to ask an Organization Owner to enable app connections for the organization, and point them to Atlas App Connections Overview. Avoid presenting the empty list as an authorization or authentication error, because the user's credentials and consent are valid.

Because delegated access carries the authorizing user's own permissions, write operations also depend on that user's roles. Common provisioning operations require the following roles:

• To create a project, the user needs the Organization Owner or Organization Project Creator role.

• To create a cluster, the user needs the Project Owner or Project Cluster Creator role on the target project.

A user who holds only the Organization Member role can read the resources they have access to, but write operations return 403 Forbidden. Name the required role in your error handling so the user can request the correct role. To learn about all available roles, see Atlas User Roles.

When your application creates an organization on a user's behalf, the new organization doesn't allow third-party app connections yet. Enabling them is a manual step: contact MongoDB to have the organization allowlisted. Until then, your application can't act on the organization, even though the user authorized your application.

Blocked and Filtered Endpoints

Delegated access reaches most Atlas Administration API endpoints, but Atlas treats some endpoints differently regardless of the authorizing user's permissions.

Blocked endpoints return a 403 Forbidden response even when the authorizing user holds a role that would normally permit the operation. Atlas blocks the federation settings endpoints, which read and modify federation and single sign-on (SSO) configuration. Identity provider configuration is shared across every organization in a federation, so delegated access to it could expose or disrupt organizations that never authorized your application.

Filtered endpoints accept the call but constrain what it can see or change, based on which organizations have opted in to third-party app connections. Your application can reach only those organizations, and Atlas blocks access to the resources of an organization that has not opted in.

Endpoints that span organizations, such as those that list every organization, project, or cluster the user can access, return only organizations that allow third-party app connections. For requests that create resources, Atlas validates the target organization and rejects the call when that organization has not opted in.

An organization owner opts in from Organization Settings > App Connections. To learn more, see Permissions and Organization Delegation Settings.

Atlas may block or filter additional endpoints for delegated access over time.

Control Plane versus Data Plane

The Atlas Administration API provides control plane access: you can create, configure, and manage Atlas resources such as organizations, projects, clusters, and users. It does not provide direct data plane access (reading or writing documents in your databases).

To access data in Atlas clusters, retrieve the cluster connection string through the Atlas Administration API and connect using a database user and the MongoDB driver or shell. The connection string and database credentials are separate from the OAuth bearer token.

Revocation affects control plane and data plane access differently. See Data Plane Effects.

Creating Database Users

Create database users through the Atlas Administration API endpoint POST /api/atlas/v2/groups/{groupId}/databaseUsers using the bearer token of the authorizing user. The user must hold a project role that permits database user management.

Recommended Practices

• Stay within the database user limit. Atlas enforces a default limit of 100 database users per project. Reuse existing database users where possible instead of creating a new user for each operation, and deprovision users you no longer need to avoid reaching the limit.

• Use scoped roles. Create database users with the minimum database roles required for your use case rather than atlasAdmin.

• Deprovision users when no longer needed. When a user revokes access to your application, delete any database users your application created on their behalf. Atlas does not automatically remove database users when access is revoked.

• Rotate credentials on a defined schedule. If your application stores database user passwords, rotate them regularly using the PATCH /api/atlas/v2/groups/{groupId}/databaseUsers/ {databaseName}/{username} endpoint.

If Atlas rotates the credentials for a resource your application provisioned, such as a database user's password, it can notify your application through an optional webhook rather than requiring you to update the credentials yourself. This is unrelated to rotating your OAuth client_secret; for that, see Token and Secret Storage. To implement the webhook, see Implement the Credential Rotation Webhook.

Encrypting Credentials at Rest

Your application handles several categories of sensitive information that must be encrypted at rest:

• Connection strings. Atlas connection strings contain embedded credentials or reference database users. Encrypt any stored connection strings using Advanced Encryption Standard (AES)-256 or equivalent encryption. Do not store connection strings in plaintext in configuration files, environment variable stores, or databases.

• OAuth tokens. Refresh tokens are long-lived credentials. Store them in an encrypted secrets manager (for example, HashiCorp Vault, Amazon Web Services (AWS) Secrets Manager, or Azure Key Vault). Do not store refresh tokens in your application database without encryption.

• Client secrets. Your client_secret is equivalent to a password. Store it in a secrets manager and rotate it if you suspect it has been exposed.

Connection String Handling

When your application retrieves connection strings from the Atlas Administration API on behalf of a user:

• Retrieve connection strings at the time they are needed rather than storing them long-term where possible.

• If your application must persist a connection string, store only what is required (for example, the hostname and port) separately from the credentials.

• Do not log connection strings or include them in error messages or stack traces.

Token and Secret Storage

• Do not commit tokens or secrets to source control.

• Do not log access tokens, refresh tokens, or client secrets. If your application logs Atlas Administration API requests for debugging, redact the Authorization header.

• Scope access to secrets in your secrets manager to only the services that require them.

• Rotate your client_secret periodically and immediately if a suspected compromise occurs. Contact MongoDB to rotate the secret associated with your OAuth application.

Revocation Triggers

Revocation can occur through any of the following actions:

• User revokes access from the Atlas UI (User Settings > Connected Apps).

• Organization owner restricts third-party app connections for the entire organization from Organization Settings.

• Refresh token expires because the organization's maximum refresh token lifetime was reached or the token was idle beyond the idle lifetime limit.

• Your application revokes its own tokens when it no longer needs access.

Revoking Tokens from Your Application

When a user disconnects your application from your own interface, or your integration otherwise no longer needs access, revoke the tokens rather than letting them expire. Send a POST request to the revocation endpoint:

curl --request POST \
  --url https://authorize.mongodb.com/tokens/revoke \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --user '<YOUR_CLIENT_ID>:<YOUR_CLIENT_SECRET>' \
  --data 'token=<REFRESH_OR_ACCESS_TOKEN>' \
  --data 'token_type_hint=refresh_token'

Revoking a refresh token also invalidates every access token issued from it. The endpoint returns 200 OK whether or not the token was valid, so treat a success response as confirmation that the token is no longer usable rather than as proof that it existed.

Control Plane Effects

How quickly revocation takes effect depends on who revokes access:

• An organization owner restricts third-party app connections: the Atlas Administration API checks the organization's delegation settings on every call, so requests against that organization begin returning 403 Forbidden immediately.

• A user revokes your application's access: the refresh token is invalidated immediately, but any access token already issued remains valid until it expires. Because access tokens are short-lived, your application may continue to make successful calls for up to 10 minutes. After that, calls return 401 Unauthorized.

• MongoDB deletes your OAuth client: revocation cascades across every organization your application is connected to, which takes up to 15 minutes to complete.

Design your application to handle 401 and 403 responses proactively rather than relying on immediate propagation.

Data Plane Effects

Revoking Atlas Administration API access does not immediately terminate existing data plane connections. Your application reaches the data plane through the database users it created, authenticating with credentials that are independent of your OAuth tokens. Revoking a token does not invalidate those credentials. Open MongoDB driver sessions and connection pool connections remain active until they are closed by normal connection lifecycle events, such as a timeout, an idle close, or an explicit close by your application.

Because revocation does not remove the database users your application created, clean them up as part of your disconnect flow. To learn more, see Database User Lifecycle.

Error Scenarios

OAuth Error Responses

Errors from the authorization and token endpoints follow the standard OAuth structure:

{
  "error": "error_code",
  "error_description": "Human-readable explanation"
}

The following table lists common error values:

If the same authorization code is presented more than once, the server invalidates all tokens associated with that grant as a security measure against code interception. When this occurs, the user must re-authorize from the start.

Disabled Clients

MongoDB can disable a registered client, for example during incident response or partner offboarding. While your client is disabled, the server refuses to start new authorization flows or issue new tokens:

• The authorization endpoint redirects the user to your redirect_uri with error=access_denied and an error_description of client is disabled.

• The token endpoint returns 401 with invalid_client and the same description. This applies to every grant type, including refresh_token, so your application cannot exchange existing refresh tokens while it is disabled.

Access tokens issued before the client was disabled remain valid until they expire. Disabling a client blocks new tokens rather than invalidating existing ones.

A disabled client cannot recover on its own. Treat client is disabled as a terminal condition: stop retrying, surface the failure, and contact the MongoDB partner team to have the client re-enabled.