MongoDB Access Tracking API

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