Bitbucket Integration via API

Purpose

This guide explains how to find your Atlassian Organization ID and generate an unscoped Organization API key, and how to use them in Logsign USO to ingest Atlassian Cloud audit events for security analytics and forensic purposes, as part of the shipped Bitbucket API integration.

Important scope note: this integration does not call a Bitbucket-specific endpoint. It calls Atlassian's Cloud organization-level Admin Audit Log API (GET /admin/v1/orgs/{orgId}/events at api.atlassian.com), which returns audit events for the entire Atlassian Cloud organization — Jira, Confluence, and Bitbucket alike, not Bitbucket only. The poller applies no product filter, so if your organization also runs Jira or Confluence, their audit events will arrive through this same source. This integration targets an Atlassian Cloud organization that includes Bitbucket; Bitbucket Server / Data Center (self-hosted) is not supported, because the poller's base URL is hardcoded to api.atlassian.com with no self-hosted equivalent.

Prerequisites

Your Atlassian organization needs an Atlassian Guard subscription (Standard or Premium tier) or at least one Enterprise plan. Without one of these, organization-level audit logs are not recorded at all and the events endpoint returns no data (source: Atlassian Support, "View audit log activities").

The account used to generate the API key must hold the organization admin role in Atlassian Administration (admin.atlassian.com).

The key must be created as an API key without scopes (unscoped). The organization events endpoint this poller calls does not support scoped API keys — Atlassian's own scopes reference states that any endpoint not listed in the scope table requires an unscoped key (source: developer.atlassian.com/cloud/admin/scopes), which third-party log integrators corroborate (source: docs.panther.com/data-onboarding/supported-logs/atlassian). A scoped key will authenticate but the events call will fail authorization.

Step 1: Find Your Organization ID

1. Sign in to https://admin.atlassian.com using an organization admin account.
2. If you manage more than one organization, select the correct one.
3. Look at the browser address bar. The URL takes the form https://admin.atlassian.com/o/<organization_id>/overview. The value after /o/ (a UUID, e.g. a1b2c3d4-e5f6-7890-...) is your Organization ID. This is the organization_id value you will enter in Logsign in Step 3.

Step 2: Create an Unscoped Organization API Key

1. In Atlassian Administration, go to Settings > API keys (this is an organization-level setting, not your personal account's API tokens page).
2. Click Create API key.
3. When asked to choose a key type, select API key without scopes. Do not select "API key with scopes" — the audit events endpoint used by this poller is not on the scoped-key endpoint list and will reject a scoped key's requests.
4. Enter a name (for example, "Logsign USO integration") and choose an expiration date. Organization API keys expire after at most one year and must be regenerated before they lapse.
5. Click Create, then copy the generated key value immediately. Atlassian will not show it to you again once you leave the screen — if you lose it, you must generate a new key.

Step 3: Configure the Integration in Logsign USO

After obtaining the Organization ID and the API key, log in to Logsign USO and add a new Bitbucket (Atlassian) data source. You will be asked for:

Logsign then periodically calls GET https://api.atlassian.com/admin/v1/orgs/<organization_id>/events. On its first run it queries a default 12-hour lookback window using the from/to parameters (server-side time filtering); this can be overridden with an optional initial_lookback_hours field, up to a maximum of 720 hours (30 days). Subsequent runs page forward using the API's cursor parameter until meta.next is empty, and track position using each event's attributes.time field (ISO 8601) so no event is processed twice.

Notes and Limits

• Organization-wide, not Bitbucket-only: the underlying API is Atlassian's organization Admin Audit Log, not a Bitbucket-specific API. If your organization also uses Jira, Confluence, or other Atlassian Cloud products, their audit events will be delivered through this same Bitbucket data source, since the poller does not filter by product.
• Cloud only: this integration only works against an Atlassian Cloud organization (fixed base URL api.atlassian.com). Bitbucket Server and Bitbucket Data Center (self-hosted) are not supported by this poller.
• Subscription requirement: without an Atlassian Guard (Standard/Premium) subscription or an Enterprise plan, the organization will not generate audit log data at all, regardless of correct credentials.
• Key type: only an unscoped ("without scopes") organization API key works with the events endpoint; a scoped key will fail authorization on every request.
• Key expiration: organization API keys expire after at most one year. If polling stops with repeated 403 responses, check first whether the key expired or was revoked in Atlassian Administration, and whether it is still the unscoped type.
• Rate limit: Atlassian's own documentation and third-party sources indicate a limit of 10 requests per minute per API path for this endpoint; this figure was found via secondary sources during this review and was not independently reproduced against a live tenant — treat it as not verified pending direct confirmation. On a 429 response the poller does not currently implement a specific backoff/retry; it logs the failure and resumes on the next scheduled run.
• Field mapping: the poller does not yet define an explicit source-field-to-Logsign-field map (COLUMN_MAP is empty in the current code); events are normalized only through the generic flattening pipeline, with two explicit exceptions: the event's time field is typed as a date/time value, and a location/IP field (if present) is typed as an IP address. Per-event Context/Type/SubType classification (event mapping) beyond the generic defaults was not verified in this review.