Implement the Credential Rotation Webhook

This page covers rotation of a database user's credentials for a resource provisioned through your integration. It's unrelated to rotating your OAuth client_secret; for that, see Token and Secret Storage in the Integrate Your App with Atlas App Connections.

When Atlas rotates the credentials for a database user associated with a resource provisioned through your integration, Atlas sends the updated credentials to your pre-registered HTTPS callback endpoint. Atlas initiates credential rotation independently, typically in response to a security incident. Implementing this endpoint is optional but recommended, because it lets end-user applications that depend on the provisioned database user receive updated credentials automatically. The endpoint doesn't update or replace the OAuth connection between your integration and Atlas.

If you don't implement the endpoint, those end-user applications don't receive rotated database user credentials automatically. You must update the credentials through another mechanism so the applications can continue authenticating to the database.

Endpoint Requirements

Expose an endpoint using the following structure:

PUT https://<your-registered-base-url>/v1/organizations/{organizationId}/projects/{projectId}/secrets

You register your base URL with Atlas during onboarding. The organizationId and projectId path parameters identify the Atlas organization and project associated with the integration. You may use a different URL structure if you agree on it with Atlas during onboarding, but the registered base URL and required identifiers must remain unambiguous.

Atlas authenticates each request with an installation-scoped bearer token established during provisioning:

Authorization: Bearer <installation-access-token>
Content-Type: application/json

Your endpoint must:

Validate the bearer token on every request, and reject invalid or expired tokens with 401 Unauthorized.
Treat the token as confidential and store it using appropriate access controls.
Use HTTPS with a TLS certificate from a trusted certificate authority. Atlas does not call endpoints over plain HTTP, and self-signed certificates aren't supported in production.

Request Body

The request body contains the credential key-value pairs to update:

{
  "secrets": [
    {
      "name": "ATLAS_CONNECTION_STRING",
      "value": "mongodb+srv://user:pass@cluster.mongodb.net/"
    },
    {
      "name": "ATLAS_DB_USERNAME",
      "value": "app_user"
    },
    {
      "name": "ATLAS_DB_PASSWORD",
      "value": "rotated_password"
    }
  ],
  "partial": true
}

Field	Required	Description
`secrets`	Required	An array of credential key-value pairs to update.
`secrets[].name`	Required	The canonical credential name, agreed with Atlas during onboarding. Treat each agreed-upon name as a stable, versioned contract.
`secrets[].value`	Required	The updated credential value. Values may contain special characters.
`partial`	Optional	When `true`, update only the supplied credentials and leave the others unchanged. When omitted or `false`, replace the full credential set.

Responses

Status	Meaning	Expected Behavior
`200 OK` or `204 No Content`	Credentials were accepted and stored successfully.	No response body is required.
`400 Bad Request`	The request body was malformed.	Return an error message that does not expose credential values.
`401 Unauthorized`	Token validation failed.	Reject the request.
`404 Not Found`	The organization or project identifier is not recognized.	Reject the request.
`5xx`	A transient server-side error occurred.	Return the error so Atlas can retry the request.

Retry and Idempotency

Atlas retries failed requests (5xx responses or network timeouts) with exponential backoff and a limited number of retries.

Your endpoint must be idempotent. You may receive duplicate requests for the same rotation event, and applying the same credential values more than once must produce the same result without error.

Security Requirements

In addition to the authentication requirements above, your endpoint must:

Encrypt credentials at rest.
Prevent credential values from appearing in application logs, request logs, error messages, telemetry, or plaintext configuration files.
Restrict access to stored credentials to the systems and personnel that require it.
Respond within 10 seconds. If persisting the new credentials requires background processing, acknowledge the request synchronously and complete the processing asynchronously.
Follow the agreed Atlas support process if you suspect your installation access token has been compromised.

Onboarding Checklist

Before Atlas can send rotated credentials to your integration, you must:

Register your callback base URL during onboarding.
Establish and securely store the installation access token on both sides.
Agree on and document credential names and update semantics.
Deploy your endpoint so that it's reachable over HTTPS.
Confirm your endpoint returns the expected status codes.
Manually test an end-to-end rotation in a non-production environment with a non-production installation.
Test duplicate delivery and retry behavior.

Additional Resources

Back

Integrate Your App with Atlas App Connections

Manage App Access