Security logs

Audit trail of login events, API key access, profile changes, and other sensitive actions on your PayMongo account.

Security logs are an audit trail of sensitive actions performed on your account. They track login events, API key access, and account changes, helping you detect unauthorized activity and maintain compliance. You can review them on the Security Logs page in the dashboard, or retrieve them with GET /v1/audit-logs using your secret key.

What security logs capture

Security logs capture the following events:

Event TypeDescriptionExample
LoginSuccessful logins to the dashboardWhen/where you logged in; device type; IP address
API key accessWhen you viewed or regenerated an API keyTimestamp; which key was viewed/regenerated
Account settings changesChanges to profile informationEmail changed from A to B; phone number updated
Payout account updatesChanges to your bank account for payoutsBank details modified
KYC/KYB document changesUpdates to identity or business verification documentsDocument resubmitted; verification status changed

How to access security logs

  1. Log in to the PayMongo dashboard
  2. Navigate to Settings → Security (or Account → Security Logs)
  3. You'll see a chronological list of recent events
  4. Each entry shows: timestamp, event type, user who performed the action, and relevant details (IP, device, etc.)
Security Logs page with login and API key access event history

Security Logs page showing a list of login and API key access events

Date range

Security logs always reflect a bounded date window. The window applies whether you're browsing the Security Logs page in the dashboard or calling GET /v1/audit-logs directly with a secret key.

Default window. When you open Security Logs without specifying a date range, the page shows the last 30 days ending today. In API terms, created_at.lte defaults to today and created_at.gte defaults to 30 days before that (both bounds inclusive).

Specifying a custom range. You can pass created_at.gte and/or created_at.lte as ISO 8601 date strings (YYYY-MM-DD) to narrow or shift the window:

Parameters suppliedEffective window
NeitherLast 30 days ending today
created_at.lte only30 days ending on created_at.lte
created_at.gte onlyFrom created_at.gte through today
BothExactly as specified

Maximum range. The date window must not span more than 90 days. A request whose range exceeds 90 days — including the default created_at.lte of today when only created_at.gte is given — is rejected before any logs are read:

GET /v1/audit-logs?created_at.gte=2026-01-01&created_at.lte=2026-11-03

400 Bad Request
{
  "errors": [
    {
      "code": "parameter_invalid",
      "detail": "The created_at date range must not exceed 90 days (created_at.lte defaults to today when omitted)."
    }
  ]
}

Supplying created_at.gte after created_at.lte also returns a 400 parameter_invalid error.

Retrieving logs via the API

GET /v1/audit-logs returns one page of security log entries, newest first. Authenticate with your secret key using HTTP Basic Auth:

curl -g "https://api.paymongo.com/v1/audit-logs?page[size]=25" \
  -u YOUR_SECRET_KEY:

Query parameters

ParameterTypeDescription
created_at.gtestring (YYYY-MM-DD)Start of the date window (inclusive). See Date range for defaults and the 90-day limit.
created_at.ltestring (YYYY-MM-DD)End of the date window (inclusive). Defaults to today.
livemodebooleantrue returns only live-mode entries; false returns only test-mode entries. Omit to return both.
user_ids[]array of stringsReturn only entries performed by one of these user IDs. Accepts at most 50 values.
event_names[]array of stringsReturn only entries whose event_name matches one of these values (for example, merchant.activated). Accepts at most 50 values.
afterstringThe next_cursor value from a previous response. Fetches the next page. Cannot be combined with page[number] greater than 1.
page[size]integerNumber of entries per page, from 1 to 100. Defaults to 10.
page[number]integer1-based page number. page[number] × page[size] must not exceed 1,000 — use after for later pages.

Response

{
  "has_more": true,
  "next_cursor": "<opaque token>",
  "data": [
    {
      "id": "...",
      "type": "audit_log",
      "attributes": { ... }
    }
  ]
}
FieldTypeDescription
has_morebooleantrue when more entries remain after this page.
next_cursorstringCursor to pass as after to fetch the next page. Present only when has_more is true.
dataarrayThe log entries on this page, newest first. Each entry's attributes include event_id, event_name, user, metadata, resource, livemode, created_at, and updated_at.
🚧

total_records is no longer returned. Use has_more and the after cursor to tell whether more entries exist.

Paginating with a cursor

Cursor pagination is the recommended way to read more than one page. Request the first page:

GET /v1/audit-logs?page[size]=25

Then pass the returned next_cursor as after, keeping the same date window and filters:

GET /v1/audit-logs?page[size]=25&after=<next_cursor>

Repeat until has_more is false. A page can contain fewer than page[size] entries — or none — while has_more is still true (see Known limitations), so check has_more rather than the number of entries returned.

Cursors work as follows:

  • Cursors are opaque — don't parse or construct them.
  • A cursor is valid only for the account that received it.
  • A cursor is tied to its date window. Changing created_at.gte or created_at.lte between requests makes the cursor invalid for the new query.

Filtering examples

Live-mode entries for specific events:

GET /v1/audit-logs?livemode=true&event_names[]=merchant.activated&event_names[]=child_account.created

Entries by specific users:

GET /v1/audit-logs?user_ids[]=<user_id_1>&user_ids[]=<user_id_2>

A specific date window:

GET /v1/audit-logs?created_at.gte=2026-10-01&created_at.lte=2026-10-31

Errors

Invalid requests return 400 Bad Request with the code parameter_invalid:

Scenariodetail
after is not a valid cursor (malformed, altered, or issued to another account)after is not a valid cursor.
after is combined with page[number] greater than 1page[number] cannot be combined with after.
after was issued for a different date windowafter is not a valid cursor for this query.
page[number] × page[size] exceeds 1,000page[number] times page[size] must not exceed 1000. Use after for later pages.
More than 50 values in user_ids[]user_ids accepts at most 50 values.
More than 50 values in event_names[]event_names accepts at most 50 values.
created_at.gte is after created_at.ltecreated_at.gte must be on or before created_at.lte (which defaults to today when omitted).
The date window exceeds 90 daysThe created_at date range must not exceed 90 days (created_at.lte defaults to today when omitted).

Downloading security logs

  • Look for a Download or Export as CSV button on the Security Logs page
  • Click to download a CSV file of all logged events
  • Use this file for compliance reviews, audits, or investigations

Interpreting log entries

Each security log entry includes:

  • Timestamp — Date and time the event occurred (in your local timezone)
  • Event type — What happened (Login, API Key Viewed, etc.)
  • User — The account owner or team member who performed the action
  • Device / IP — For login events: browser/OS and IP address of the login
  • Details — Additional context (which API key, what changed, etc.)

Example:

2024-04-22 14:32:15 | Login | Alice Merchant | Safari on macOS | IP: 203.0.113.45
2024-04-22 14:35:02 | API Key Viewed | Alice Merchant | Secret Key | Requested
2024-04-22 15:10:00 | Payout Account Updated | Alice Merchant | Bank account changed

Known limitations

🚧

Not all account configuration changes are captured in security logs. Specifically:

  • Changes made via internal API calls (outside the dashboard UI) may not appear in security logs
  • Some backend configuration changes may not be logged

PayMongo is actively working to improve audit log coverage. Until then, if you need a complete audit trail for compliance or to investigate unusual activity, contact [email protected].

📘

A page can return fewer entries than page[size], or none, while more remain. Each API request checks at most 5,000 log entries. When filters such as event_names[] or user_ids[] match only a few entries in a busy date window, the request can stop before it fills the page. Keep requesting with after until has_more is false — a short or empty page doesn't mean you've reached the end.

How PayMongo handles security log requests

PayMongo does not proactively release security logs to third parties or regulators on your behalf. You can export logs from the dashboard and share them yourself when needed.

Suspected compromise

If you notice unusual login activity or believe your account has been compromised:

  1. Change your password immediately
  2. Check security logs for unfamiliar logins or API key access
  3. Regenerate your API keys if necessary
  4. Contact PayMongo support at [email protected] to report the incident
  5. Support will investigate and may require additional identity verification

For regulatory or compliance audits

If you need to provide security logs to regulators, auditors, or legal teams:

  • You can download logs from the dashboard and share them directly
  • For assistance with special requests or extended history, contact [email protected]

Next steps


Did this page help you?