Engramma

Security

intermediate

Audit logs, session management, and session revocation endpoints for account security.

Audit log

GET/v1/security/audit-log

Retrieve the audit log for your account or organization. Shows all security-relevant actions.

org_idstring

Filter by organization. If omitted, shows personal account actions.

actionstring

Filter by action type (e.g., login, key_created, member_removed).

fromstring

ISO 8601 start date for the log range.

tostring

ISO 8601 end date for the log range.

pageintegerDefault: 1

Page number.

per_pageintegerDefault: 50

Items per page (max 100).

200Response
{
  "data": [
    {
      "id": "audit_abc123",
      "action": "login",
      "actor": {
        "id": "usr_abc123",
        "email": "[email protected]",
        "type": "user"
      },
      "details": {
        "method": "password",
        "mfa_used": true,
        "ip": "203.0.113.42",
        "user_agent": "Mozilla/5.0..."
      },
      "timestamp": "2026-01-20T14:30:00Z",
      "success": true
    },
    {
      "id": "audit_def456",
      "action": "key_created",
      "actor": {
        "id": "usr_abc123",
        "email": "[email protected]",
        "type": "user"
      },
      "details": {
        "key_id": "key_new789",
        "key_name": "Staging Environment",
        "scopes": [
          "memory:read",
          "memory:write"
        ]
      },
      "timestamp": "2026-01-20T14:35:00Z",
      "success": true
    },
    {
      "id": "audit_ghi789",
      "action": "login_failed",
      "actor": {
        "id": null,
        "email": "[email protected]",
        "type": "unknown"
      },
      "details": {
        "reason": "invalid_password",
        "ip": "198.51.100.23",
        "attempts": 3
      },
      "timestamp": "2026-01-20T13:00:00Z",
      "success": false
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 234,
    "total_pages": 5
  }
}
import os
from engramma_cloud import EngrammaClient

client = EngrammaClient(api_key=os.environ["ENGRAMMA_API_KEY"])

# Get recent security events
audit = client.security.audit_log(
    org_id="org_abc123",
    from_date="2026-01-20"
)
for entry in audit:
    status = "OK" if entry.success else "FAILED"
    print(f"[{status}] {entry.action} by {entry.actor.email} at {entry.timestamp}")

Audit action types

ActionDescription
loginSuccessful login
login_failedFailed login attempt
logoutUser logged out
mfa_enabledMFA was enabled
mfa_disabledMFA was disabled
password_changedPassword was changed
password_resetPassword was reset via email
key_createdAPI key created
key_revokedAPI key revoked
key_rotatedAPI key rotated
member_invitedMember invitation sent
member_joinedMember accepted invitation
member_removedMember removed from org
role_changedMember role changed
plan_changedSubscription plan changed
data_exportedGDPR data export requested
erasure_requestedGDPR erasure requested

List sessions

GET/v1/security/sessions

List all active sessions for your account.

200Response
{
  "sessions": [
    {
      "id": "sess_abc123",
      "current": true,
      "ip": "203.0.113.42",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "location": "Paris, France",
      "created_at": "2026-01-20T14:30:00Z",
      "last_active_at": "2026-01-20T15:45:00Z"
    },
    {
      "id": "sess_def456",
      "current": false,
      "ip": "198.51.100.23",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)",
      "location": "London, UK",
      "created_at": "2026-01-18T09:00:00Z",
      "last_active_at": "2026-01-19T22:00:00Z"
    }
  ]
}
sessions = client.security.sessions()
for s in sessions:
    current = " (current)" if s.current else ""
    print(f"{s.location} — {s.user_agent[:40]}...{current}")
    print(f"  Last active: {s.last_active_at}")

Revoke session

DELETE/v1/security/sessions/{session_id}

Revoke a specific session. The session's tokens are immediately invalidated.

session_idstringrequired

Session ID to revoke (path parameter).

200Response
{
  "revoked": true,
  "session_id": "sess_def456",
  "revoked_at": "2026-01-20T15:00:00Z"
}
# Revoke a suspicious session
client.security.revoke_session(session_id="sess_def456")
print("Session revoked")
Tip

If you notice an unfamiliar session, revoke it immediately and change your password. Enable MFA if not already active.

Security recommendations

  1. Enable MFA — Protects against password compromise. See Authentication endpoints.

  2. Review sessions regularly — Revoke any session you don't recognize.

  3. Monitor the audit log — Watch for failed login attempts or unexpected key creations.

  4. Rotate API keys — See API Keys reference for rotation with grace period.

  5. Use scoped keys — Give each key only the permissions it needs.

Next steps

WebhooksErrors