Navigation

Get Database Access History for a Cluster by Hostname

Retrieve the access logs of a cluster by hostname.

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.

Feature unavailable in Free and Shared-Tier Clusters

This feature is not available for M0 (Free Tier), M2, and M5 clusters. To learn more about which features are unavailable, see Atlas M0 (Free Tier), M2, and M5 Limitations.

The Atlas API uses HTTP Digest Authentication. Provide a programmatic API public key and corresponding private key as the username and password when constructing the HTTP request.

For complete documentation on configuring API access for an Atlas project, see Configure Atlas API Access.

Base URL: https://cloud.mongodb.com/api/atlas/v1.0

Resource

GET /groups/{GROUP-ID}/dbAccessHistory/processes/{HOSTNAME}

Request Path Parameters

Path Element Required/Optional Description
GROUP-ID Required. The unique identifier for the project.
HOSTNAME Required. The hostname of the cluster.

Request Query Parameters

The following query parameters are optional:

Name Type Description Default
start long UNIX timestamp in milliseconds of the first date to return database access logs from. Current timestamp minus 30 days
end long UNIX timestamp in milliseconds of the last date to return database access logs from. Current timestamp
nLogs integer Maximum number of logs to return. Valid values are 0 - 20000. 20000
ipAddress string Filters the log to return authentication attempts from the specified IP address only. Maximum of one IP address.  
authResult boolean Specifies whether to return either successful or failed authentication attempts. When set to true, filters the log to return only successful authentication attempts. When set to false, filters the log to return only failed authentication attempts.  

Request Body Parameters

This endpoint does not use HTTP request body parameters.

Response

Name Type Description
accessLogs object array The authentication attempts made against the cluster. Each object is a separate attempt.
authResult boolean The result of the authentication attempt. Returns true if the authentication request was successful. Returns false if the authentication request resulted in failure.
authSource string The database that the request attempted to authenticate against. Returns admin if the authentication source for the user is SCRAM-SHA. Returns $external if the authentication source for the user is LDAP.
failureReason string The reason that the request failed to authenticate. Returns null if the authentication request was successful.
groupId string The unique identifier for the project.
hostname string The hostname of the target node that received the authentication attempt.
clusterName string The name associated with the cluster.
ipAddress string The IP address that the authentication attempt originated from.
logLine string The text of the server log concerning the authentication attempt.
timestamp string The UTC timestamp of the authentication attempt.
username string The username that attempted to authenticate.

Example Request

curl -u "username:apiKey" --digest \
 --header "Accept: application/json" \
 --header "Content-Type: application/json" \
 --request GET "https://cloud.mongodb.com/api/atlas/v1.0/groups/571c390a7cea7e4dbf32b625/dbAccessHistory/processes/cluster0-shard-00-00-c01ab.mongodb.net:27017?start=1564064082000&end=1564064082000&nLogs=2"

Example Response

Response Header

HTTP/1.1 200 OK
Vary: Accept-Encoding
Content-Type: application/json
Strict-Transport-Security: max-age=300
Date: {dateInUnixFormat}
Connection: keep-alive
Content-Length: {requestLengthInBytes}

Response Body

{
  "accessLogs": [
    {
      "authResult": true,
      "authSource": "admin",
      "failureReason": null,
      "groupId": "571c390a7cea7e4dbf32b625",
      "hostname": "cluster0-shard-00-00-c01ab.mongodb.net:27017",
      "clusterName": "cluster0",
      "ipAddress": "123.45.0.1",
      "logLine": "2019-07-25T19:14:42.484+0000 I  ACCESS   [conn2167] Successfully authenticated as principal jon-snow on admin from client 123.45.0.1:8080",
      "timestamp": "Sun Jul 25 9:14:42 EDT 2019",
      "username": "jon-snow"
    },
    {
      "authResult": false,
      "authSource": "admin",
      "failureReason": "UserNotFound: Could not find user \"jane-doe\" for db \"admin\"",
      "groupId": "571c390a7cea7e4dbf32b625",
      "hostname": "cluster0-shard-00-00-c01ab.mongodb.net:27017",
      "clusterName": "cluster0",
      "ipAddress": "123.45.2.2",
      "logLine": "2019-07-25T19:13:39.316+0000 I  ACCESS   [conn1893] SASL SCRAM-SHA-1 authentication failed for jane-doe on admin from client 123.45.2.2:51842 ; UserNotFound: Could not find user \"jane-doe\" for db \"admin\"",
      "timestamp": "Sun Jul 25 9:14:42 EDT 2019",
      "username": "jane-doe"
    }
]}