openapi: 3.0.1 info: description: "The MongoDB Atlas Administration API allows developers to manage all components in MongoDB Atlas.\n\nThe Atlas Administration API supports OAuth2 Service Accounts and HTTP Digest-based API keys. Service accounts are the recommended authentication method and API keys are considered a legacy option.\n\nTo authenticate with a Service Account, first exchange its client ID and secret for an access token using the OAuth 2.0 Client Credentials flow. Atlas provides a token endpoint at `POST https://cloud.mongodb.com/api/oauth/token`, which returns a Bearer token that is reusable and valid for 1 hour (3600 seconds).\n\nFor example, to [return a list of your organizations](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-listorgs) with [cURL](https://en.wikipedia.org/wiki/CURL), first generate an access token and then use that token to call the same Atlas Administration API endpoint shown in the current example:\n\n```\nACCESS_TOKEN=$(curl -fsS --request POST https://cloud.mongodb.com/api/oauth/token \\\n --header \"Authorization: Basic $(printf '%s' \"${CLIENT_ID}:${CLIENT_SECRET}\" | base64 | tr -d '\\n')\" \\\n --header \"Content-Type: application/x-www-form-urlencoded\" \\\n --header \"Accept: application/json\" \\\n --data \"grant_type=client_credentials\" | jq -r '.access_token')\n\ncurl --header \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n --header \"Accept: application/vnd.atlas.2025-03-12+json\" \\\n -X GET \"https://cloud.mongodb.com/api/atlas/v2/orgs?pretty=true\"\n```\n\nIf your organization requires an IP access list for the Atlas Administration API, the token can be created from any IP address, but the API call that uses the token must originate from an allowed IP.\n\nTo learn more, see [Get Started with the Atlas Administration API](https://www.mongodb.com/docs/atlas/configure-api-access/). For support, see [MongoDB Support](https://www.mongodb.com/support/get-started).\n\nYou can also explore the various endpoints available through the Atlas Administration API in MongoDB's [Postman workspace](https://www.postman.com/mongodb-devrel/workspace/mongodb-atlas-administration-apis/) (requires a Postman account)." license: name: CC BY-NC-SA 3.0 US url: https://creativecommons.org/licenses/by-nc-sa/3.0/us/ termsOfService: https://www.mongodb.com/mongodb-management-service-terms-and-conditions title: MongoDB Atlas Administration Access Tracking API version: '2.0' x-xgen-sha: 3d70e065843c008b9871ea7836c98c9de6f202f9 servers: - url: https://cloud.mongodb.com security: - ServiceAccounts: [] - DigestAuth: [] tags: - description: Returns access logs for authentication attempts made to Atlas database deployments. To view database access history, you must have either the Project Owner or Organization Owner role. name: Access Tracking paths: /api/atlas/v2/groups/{groupId}/dbAccessHistory/clusters/{clusterName}: get: description: Returns the access logs of one cluster identified by the cluster's name. Access logs contain a list of authentication requests made against your cluster. You can't use this feature on tenant-tier clusters (M0, M2, M5). To use this resource, the requesting Service Account or API Key must have the Project Monitoring Admin role, the Project Database Access Admin role, or the Project Cluster Log Viewer role. externalDocs: description: Database Access History url: https://docs.atlas.mongodb.com/access-tracking/ operationId: getGroupDbAccessHistoryCluster parameters: - $ref: '#/components/parameters/envelope' - $ref: '#/components/parameters/groupId' - $ref: '#/components/parameters/pretty' - description: Flag that indicates whether the response returns the successful authentication attempts only. in: query name: authResult schema: type: boolean - description: Human-readable label that identifies the cluster. in: path name: clusterName required: true schema: pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]*$ type: string - description: Date and time when to stop retrieving database history. If you specify **end**, you must also specify **start**. This parameter uses UNIX epoch time in milliseconds. in: query name: end schema: format: int64 minimum: 1199145600000 type: integer - description: One Internet Protocol address that attempted to authenticate with the database. in: query name: ipAddress schema: pattern: ^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)(\.(?!$)|$)){4}|([0-9a-f]{1,4}:){7}[0-9a-f]{1,4}$ type: string - description: Maximum number of lines from the log to return. in: query name: nLogs schema: default: 20000 format: int32 maximum: 20000 minimum: 0 type: integer - description: Date and time when MongoDB Cloud begins retrieving database history. If you specify **start**, you must also specify **end**. This parameter uses UNIX epoch time in milliseconds. in: query name: start schema: format: int64 minimum: 1199145600000 type: integer responses: '200': content: application/vnd.atlas.2023-01-01+json: schema: $ref: '#/components/schemas/MongoDBAccessLogsList' x-xgen-version: '2023-01-01' description: OK headers: RateLimit-Limit: $ref: '#/components/headers/HeaderRateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/HeaderRateLimitRemaining' '400': $ref: '#/components/responses/badRequest' '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' '429': $ref: '#/components/responses/tooManyRequests' '500': $ref: '#/components/responses/internalServerError' summary: Return Database Access History for One Cluster by Cluster Name tags: - Access Tracking x-codeSamples: - lang: cURL label: Atlas CLI source: atlas api accessTracking getAccessHistoryCluster --help - lang: go label: Go source: "import (\n\t\"os\"\n\t\"context\"\n\t\"log\"\n\tsdk \"go.mongodb.org/atlas-sdk/v20250312001/admin\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclientID := os.Getenv(\"MONGODB_ATLAS_CLIENT_ID\")\n\tclientSecret := os.Getenv(\"MONGODB_ATLAS_CLIENT_SECRET\")\n\n\t// See https://dochub.mongodb.org/core/atlas-go-sdk-oauth\n\tclient, err := sdk.NewClient(sdk.UseOAuthAuth(clientID, clientSecret))\n\n\tif err != nil {\n\t\tlog.Fatalf(\"Error: %v\", err)\n\t}\n\n\tparams = &sdk.GetGroupDbAccessHistoryClusterApiParams{}\n\tsdkResp, httpResp, err := client.AccessTrackingApi.\n\t\tGetGroupDbAccessHistoryClusterWithParams(ctx, params).\n\t\tExecute()\n}\n" - lang: cURL label: curl (Service Accounts) source: "curl --include --header \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n --header \"Accept: application/vnd.atlas.2025-03-12+json\" \\\n -X GET \"https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/dbAccessHistory/clusters/{clusterName}?pretty=true\"" - lang: cURL label: curl (Digest) source: "curl --user \"${PUBLIC_KEY}:${PRIVATE_KEY}\" \\\n --digest --include \\\n --header \"Accept: application/vnd.atlas.2025-03-12+json\" \\\n -X GET \"https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/dbAccessHistory/clusters/{clusterName}?pretty=true\"" x-rolesRequirements: - Project Cluster Log Viewer - Project Database Access Admin x-xgen-docs-url: https://mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Access-Tracking/operation/getGroupDbAccessHistoryCluster x-xgen-operation-id-override: getAccessHistoryCluster /api/atlas/v2/groups/{groupId}/dbAccessHistory/processes/{hostname}: get: description: Returns the access logs of one cluster identified by the cluster's hostname. Access logs contain a list of authentication requests made against your clusters. You can't use this feature on tenant-tier clusters (M0, M2, M5). To use this resource, the requesting Service Account or API Key must have the Project Monitoring Admin role, the Project Database Access Admin role, or the Project Cluster Log Viewer role. externalDocs: description: Database Access History url: https://docs.atlas.mongodb.com/access-tracking/ operationId: getGroupDbAccessHistoryProcess parameters: - $ref: '#/components/parameters/envelope' - $ref: '#/components/parameters/groupId' - $ref: '#/components/parameters/pretty' - description: Flag that indicates whether the response returns the successful authentication attempts only. in: query name: authResult schema: type: boolean - description: Date and time when to stop retrieving database history. If you specify **end**, you must also specify **start**. This parameter uses UNIX epoch time in milliseconds. in: query name: end schema: format: int64 minimum: 1199145600000 type: integer - description: Fully qualified domain name or IP address of the MongoDB host that stores the log files that you want to download. in: path name: hostname required: true schema: type: string - description: One Internet Protocol address that attempted to authenticate with the database. in: query name: ipAddress schema: pattern: ^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)(\.(?!$)|$)){4}|([0-9a-f]{1,4}:){7}[0-9a-f]{1,4}$ type: string - description: Maximum number of lines from the log to return. in: query name: nLogs schema: default: 20000 format: int32 maximum: 20000 minimum: 0 type: integer - description: Date and time when MongoDB Cloud begins retrieving database history. If you specify **start**, you must also specify **end**. This parameter uses UNIX epoch time in milliseconds. in: query name: start schema: format: int64 minimum: 1199145600000 type: integer responses: '200': content: application/vnd.atlas.2023-01-01+json: schema: $ref: '#/components/schemas/MongoDBAccessLogsList' x-xgen-version: '2023-01-01' description: OK headers: RateLimit-Limit: $ref: '#/components/headers/HeaderRateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/HeaderRateLimitRemaining' '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' '429': $ref: '#/components/responses/tooManyRequests' '500': $ref: '#/components/responses/internalServerError' summary: Return Database Access History for One Cluster by Hostname tags: - Access Tracking x-codeSamples: - lang: cURL label: Atlas CLI source: atlas api accessTracking getAccessHistoryProcess --help - lang: go label: Go source: "import (\n\t\"os\"\n\t\"context\"\n\t\"log\"\n\tsdk \"go.mongodb.org/atlas-sdk/v20250312001/admin\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclientID := os.Getenv(\"MONGODB_ATLAS_CLIENT_ID\")\n\tclientSecret := os.Getenv(\"MONGODB_ATLAS_CLIENT_SECRET\")\n\n\t// See https://dochub.mongodb.org/core/atlas-go-sdk-oauth\n\tclient, err := sdk.NewClient(sdk.UseOAuthAuth(clientID, clientSecret))\n\n\tif err != nil {\n\t\tlog.Fatalf(\"Error: %v\", err)\n\t}\n\n\tparams = &sdk.GetGroupDbAccessHistoryProcessApiParams{}\n\tsdkResp, httpResp, err := client.AccessTrackingApi.\n\t\tGetGroupDbAccessHistoryProcessWithParams(ctx, params).\n\t\tExecute()\n}\n" - lang: cURL label: curl (Service Accounts) source: "curl --include --header \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n --header \"Accept: application/vnd.atlas.2025-03-12+json\" \\\n -X GET \"https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/dbAccessHistory/processes/{hostname}?pretty=true\"" - lang: cURL label: curl (Digest) source: "curl --user \"${PUBLIC_KEY}:${PRIVATE_KEY}\" \\\n --digest --include \\\n --header \"Accept: application/vnd.atlas.2025-03-12+json\" \\\n -X GET \"https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/dbAccessHistory/processes/{hostname}?pretty=true\"" x-rolesRequirements: - Project Cluster Log Viewer - Project Database Access Admin x-xgen-docs-url: https://mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Access-Tracking/operation/getGroupDbAccessHistoryProcess x-xgen-operation-id-override: getAccessHistoryProcess components: headers: HeaderRateLimitLimit: description: The maximum number of requests that a user can make within a specific time window. schema: type: integer HeaderRetryAfter: description: The minimum time you should wait, in seconds, before retrying the API request. This header might be returned for 429 or 503 error responses. schema: type: integer HeaderRateLimitRemaining: description: The number of requests remaining in the current rate limit window before the limit is reached. schema: type: integer responses: badRequest: content: application/json: example: detail: (This is just an example, the exception may not be related to this endpoint) No provider AWS exists. error: 400 errorCode: VALIDATION_ERROR reason: Bad Request schema: $ref: '#/components/schemas/ApiError' description: Bad Request. internalServerError: content: application/json: example: detail: (This is just an example, the exception may not be related to this endpoint) error: 500 errorCode: UNEXPECTED_ERROR reason: Internal Server Error schema: $ref: '#/components/schemas/ApiError' description: Internal Server Error. tooManyRequests: content: application/json: example: detail: (This is just an example, the exception may not be related to this endpoint) error: 429 errorCode: RATE_LIMITED reason: Too Many Requests schema: $ref: '#/components/schemas/ApiError' description: Too Many Requests. headers: RateLimit-Limit: $ref: '#/components/headers/HeaderRateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/HeaderRateLimitRemaining' Retry-After: $ref: '#/components/headers/HeaderRetryAfter' notFound: content: application/json: example: detail: (This is just an example, the exception may not be related to this endpoint) Cannot find resource AWS error: 404 errorCode: RESOURCE_NOT_FOUND reason: Not Found schema: $ref: '#/components/schemas/ApiError' description: Not Found. unauthorized: content: application/json: example: detail: (This is just an example, the exception may not be related to this endpoint) error: 401 errorCode: NOT_ORG_GROUP_CREATOR reason: Unauthorized schema: $ref: '#/components/schemas/ApiError' description: Unauthorized. forbidden: content: application/json: example: detail: (This is just an example, the exception may not be related to this endpoint) error: 403 errorCode: CANNOT_CHANGE_GROUP_NAME reason: Forbidden schema: $ref: '#/components/schemas/ApiError' description: Forbidden. parameters: groupId: description: 'Unique 24-hexadecimal digit string that identifies your project. Use the [/groups](#tag/Projects/operation/listProjects) endpoint to retrieve all projects to which the authenticated user has access. **NOTE**: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.' in: path name: groupId required: true schema: example: 32b6e34b3d91647abb20e7b8 pattern: ^([a-f0-9]{24})$ type: string pretty: description: Flag that indicates whether the response body should be in the prettyprint format. in: query name: pretty schema: default: false externalDocs: description: Prettyprint url: https://en.wikipedia.org/wiki/Prettyprint type: boolean envelope: description: Flag that indicates whether Application wraps the response in an `envelope` JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body. in: query name: envelope schema: default: false type: boolean schemas: BadRequestDetail: description: Bad request detail. properties: fields: description: Describes all violations in a client request. items: $ref: '#/components/schemas/FieldViolation' type: array readOnly: true type: object FieldViolation: properties: description: description: A description of why the request element is bad. type: string field: description: A path that leads to a field in the request body. type: string required: - description - field type: object MongoDBAccessLogs: description: Authentication attempt, one per object, made against the cluster. properties: authResult: description: Flag that indicates whether the response should return successful authentication attempts only. type: boolean authSource: description: Database against which someone attempted to authenticate. readOnly: true type: string failureReason: description: Reason that the authentication failed. Null if authentication succeeded. readOnly: true type: string groupId: description: Unique 24-hexadecimal character string that identifies the project. readOnly: true type: string hostname: description: Human-readable label that identifies the hostname of the target node that received the authentication attempt. readOnly: true type: string ipAddress: description: Internet Protocol address that attempted to authenticate with the database. pattern: ^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)(\.(?!$)|$)){4}|([0-9a-f]{1,4}:){7}[0-9a-f]{1,4}$ readOnly: true type: string logLine: description: Text of the host log concerning the authentication attempt. readOnly: true type: string timestamp: description: Date and time when someone made this authentication attempt. MongoDB Cloud represents this timestamp in ISO 8601 format in UTC. readOnly: true type: string username: description: Username used to authenticate against the database. readOnly: true type: string type: object ApiError: properties: badRequestDetail: $ref: '#/components/schemas/BadRequestDetail' detail: description: Describes the specific conditions or reasons that cause each type of error. type: string error: description: HTTP status code returned with this error. externalDocs: url: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status format: int32 readOnly: true type: integer errorCode: description: Application error code returned with this error. readOnly: true type: string parameters: description: Parameters used to give more information about the error. items: type: object readOnly: true type: array reason: description: Application error message returned with this error. readOnly: true type: string required: - error - errorCode type: object MongoDBAccessLogsList: properties: accessLogs: description: Authentication attempt, one per object, made against the cluster. items: $ref: '#/components/schemas/MongoDBAccessLogs' readOnly: true type: array type: object securitySchemes: DigestAuth: scheme: digest type: http ServiceAccounts: description: Learn more about [Service Accounts](https://www.mongodb.com/docs/atlas/api/service-accounts-overview). flows: clientCredentials: scopes: {} tokenUrl: https://cloud.mongodb.com/api/oauth/token type: oauth2 x-externalLinks: - label: Back to Atlas Docs url: https://www.mongodb.com/docs/atlas/ - label: API Changelog url: https://www.mongodb.com/docs/atlas/reference/api-resources-spec/changelog/ x-topics: - content: The MongoDB Atlas Administration API is rate limited. To learn more about rate limiting, see the [Atlas Documentation on Rate Limiting](http://dochub.mongodb.org/core/atlas-api-rate-limit) title: Rate Limiting