Skip to content

Security and audit

List security alerts

Returns things that looked unusual, newest first, one page at a time. Owners, admins and admin API keys get the alerts of the whole workspace; agents signed in to the app get only the alerts about themselves.

GET/api/v1/security/alerts
  • 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

  • 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<SecurityAlert>

    Alerts, newest first.

    Show child attributesHide child attributes14
    • iduuid

      Alert id.

    • kindenum

      new_device, new_country, failed_logins, api_key_new_ip, large_data_access, admin_added or api_key_created. See the list below.

    • summarystring

      One sentence that says what happened.

    • user_iduuidnullable

      The teammate the alert is about, or null.

    • user_namestring

      Their name, or "".

    • api_key_iduuidnullable

      The API key the alert is about, or null.

    • api_key_namestring

      Its name, or "".

    • ipstring

      IP address involved, or "".

    • locationstring

      City and country of that address (for example Ljubljana, SI), or "".

    • devicestring

      Browser and operating system, or "".

    • countinteger

      How many times it happened. Repeats within the same hour raise the count instead of adding alerts.

    • emailedboolean

      true when an email about the alert was sent.

    • created_attimestamp

      First occurrence (RFC 3339).

    • last_seen_attimestamp

      Latest occurrence (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 alerts.
  • 400Bad request. Session requests only: no workspace was selected (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).
  • 500Server error. Something went wrong on our side. Retry with backoff.

Which alerts are there?

kindWhen
new_deviceA teammate signed in from a device their account had not used before.
new_countryA teammate signed in from a country their account had not signed in from before.
failed_loginsRepeated failed sign-ins to a teammate’s account.
api_key_new_ipAn API key was used from an IP address it had not been used from before.
large_data_accessAn unusually large amount of data was read or exported.
admin_addedSomeone was given the admin role.
api_key_createdA new API key was created.

The same alert about the same person or key is raised at most once an hour: repeats within the hour raise count and last_seen_at instead of adding a new alert. Handle kinds you do not recognise: new ones may be added.

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.