Skip to content

Security and audit

List audit events

Returns the workspace’s audit events, newest first, one page at a time: every sign-in, message sent, export, team, key and connection change, with the teammate or API key that did it. Owners and admins only (and admin API keys).

GET/api/v1/security/audit
  • Bearer API key
  • Scope: admin only
  • or app session
  • Workspace: X-Tenant-ID (optional with a key)

Headers

  • Authorizationstringrequired

    Your API key as Bearer <key>. The word Bearer and the space are case-sensitive. Browser clients signed in to the app use the session cookie instead.

    Constraints
    Keys start with pk_live_ and are 56 characters long.
    Example
    Bearer pk_live_…
  • X-Tenant-IDuuidoptional

    Workspace id. Optional with an API key (a key always acts in its own workspace); if you send it, it must match the key’s workspace. Required with a session cookie. You can pass ?tenant=<id> instead.

    Example
    8d0f6c2e-3b1a-4c55-9a7e-2f4b6d1e9c30

Query parameters

  • user_iduuidoptional

    Only this teammate (their user id, user_id in the members list).

  • api_key_iduuidoptional

    Only actions done with this API key (its id, not the key itself).

  • actionstringoptional

    Only this action, for example member.role_changed. End it with * to match a prefix: message.* returns message.sent, message.edited and message.deleted.

    Example
    message.*
  • fromtimestampoptional

    Only entries from this time on. RFC 3339 (2026-10-01T00:00:00Z) or a date (2026-10-01).

    Example
    2026-10-01
  • totimestampoptional

    Only entries before this time (exclusive). RFC 3339 or a date: to include all of 8 October, send to=2026-10-09.

  • cursorstringoptional

    The next_cursor of the previous page, unchanged. Leave it out to get the first page.

  • limitintegeroptional

    Items per page.

    Constraints
    At most 200.
    Default
    50
    Example
    50

Response

200 OKapplication/json

  • itemsarray<AuditEvent>

    Audit events, newest first.

    Show child attributesHide child attributes14
    • idstring

      Event id.

    • actionstring

      What happened, for example message.sent. See the list of actions below.

    • actor_typeenum

      user, api_key or system.

    • actor_user_iduuidnullable

      The teammate who did it, when actor_type is user.

    • actor_api_key_iduuidnullable

      The API key that did it, when actor_type is api_key.

    • actor_namestring

      Name of the teammate or API key, or "" for the system.

    • viaenum

      web (the app), api (an API key) or system.

    • resource_typestring

      Kind of thing acted on, for example conversation, or "".

    • resource_idstring

      Its id, or "".

    • detailobject

      Small extra facts that depend on the action, such as endpoint, count, conversation_id, role, from_role, to_role, email, area, method, rows or scope. Never message text. {} when there are none.

    • ipstring

      IP address of the request, or "".

    • user_agentstring

      User agent of the request, or "".

    • devicestring

      Browser and operating system read from it, for example Chrome on macOS.

    • created_attimestamp

      When it happened (RFC 3339).

  • next_cursorstring

    Send it as cursor to get the next page. An empty string ("") means this is the last page.

Status codes

  • 200OK. One page of audit events.
  • 400Bad request. A filter is malformed: invalid from or invalid to (neither RFC 3339, YYYY-MM-DD nor unix seconds), invalid user_id, invalid result or invalid cursor. A session request without a workspace gets workspace required (X-Tenant-ID).
  • 401Unauthorized. The API key is unknown, revoked or expired (invalid or expired API key), or there is no key and no signed-in session (unauthorized).
  • 403Forbidden. The API key does not have the admin scope (this endpoint needs an API key with the admin scope: read and write keys cannot read security data); the key is limited to other IP addresses (this API key is not allowed from your IP address, code: "ip_not_allowed"); or the key or user belongs to another workspace (API key belongs to a different workspace, forbidden). The audit log is for owners and admins: agents signed in to the app always get 403 (admin required).
  • 500Server error. Something went wrong on our side. Retry with backoff.

Which actions are recorded?

ActionWhen
auth.login, auth.login_failed, auth.logoutA member signed in, failed to sign in, or signed out.
session.revoked, session.revoked_othersA session was signed out, or a member signed out all their other sessions.
message.sent, attachment.sentA text message or a file was sent.
message.edited, message.deletedA sent message was edited or deleted for everyone.
conversation.opened, conversation.assignedA conversation was opened, or assigned to a teammate.
api.fetchAn API key read data (detail.endpoint and detail.count).
api_key.created, api_key.updated, api_key.revokedAn API key was created, its IP allowlist changed, or it was revoked.
api_key.ip_deniedAn API key was used from an IP address outside its allowed_ips.
member.invited, member.added, member.removed, member.role_changedTeam changes (detail.email, detail.role, detail.from_role, detail.to_role).
invite.revoked, invite.resentA pending invite was revoked or sent again.
whatsapp.connect, whatsapp.pair_phone, whatsapp.disconnect, whatsapp.logged_outLinking a number by QR code or phone number, unlinking it, or the phone logging the link out.
channel.saved, channel.deletedCloud API channel settings were saved or removed.
settings.changedWorkspace settings changed (detail.area).
export.contacts_csv, export.participants_csv, export.audit_csvContacts, group members or the audit log were downloaded as CSV (detail.rows).

actor_type and via say who did it: a teammate in the app (user, web), an API key (api_key, api) or whatsappx.si itself (system). Handle action names you do not recognise: new ones may be added.

Can entries be changed?

No. The audit log is append-only: entries cannot be edited or deleted from the app or the API. detail never holds message text.

How do I page through the list?

Items come newest first, limit at a time (50 by default, at most 200). While next_cursor is not empty, call the endpoint again with the same filters and cursor=<next_cursor>. An empty next_cursor ("") means you have the last page.